MT-23076: support api token expiration in create and reset

[oshchyhol]

Motivation

MT-23076

The API token endpoints now support an expires_at attribute. This exposes it in the Python SDK so tokens can be created or reset with an explicit expiry, with no expiry, or with the server default.

Changes

• createApiToken: CreateApiTokenParams gains an optional expires_at (ISO 8601 date-time, nullable). Omitted – key absent from the request body (server default, a 1-year default is being rolled out); explicit None – "expires_at": null (never expires); string – sent as is
• resetApiToken: the request body is now optional per the spec; new ResetApiTokenParams with the same expires_at field, and reset() accepts an optional token_params argument. Without it, the request still has no body, byte-identical to before
• new UNSET sentinel (UnsetType in mailtrap/models/common.py) keeps "field omitted" distinct from an explicit None; RequestParams.api_data drops UNSET values. Exported as mt.UNSET together with mt.ResetApiTokenParams
• no client-side date validation: past, unparseable, or more-than-5-years-ahead values surface as the server's 422 via the standard APIError
• examples/general/api_tokens.py extended with expiration usage

How to test

• api_tokens.create(account_id, mt.CreateApiTokenParams(name="My token")) – request body has no expires_at key, token is created exactly as before the change
• api_tokens.create(account_id, mt.CreateApiTokenParams(name="My token", expires_at=None)) – request body contains "expires_at": null, response has expires_at: None (never expires)
• api_tokens.create(account_id, mt.CreateApiTokenParams(name="My token", expires_at="2027-06-01T00:00:00Z")) – request body contains that date-time, response echoes it
• create with a past date (or one more than 5 years ahead) – SDK raises APIError with the server's 422 message
• api_tokens.reset(account_id, token_id) without params – request has no body (same as before), reset works unchanged
• api_tokens.reset(account_id, token_id, token_params=mt.ResetApiTokenParams(expires_at=None)) – request body is {"expires_at": null}, new token never expires
• api_tokens.reset(account_id, token_id, token_params=mt.ResetApiTokenParams(expires_at="2027-06-01T00:00:00Z")) – request body contains that date-time
• list/get/delete API tokens and other params classes (e.g. contacts, webhooks) – behavior unchanged

Companion PRs

• other MT-23076 SDK PRs: MT-23076: support expires_at on api token create and reset mailtrap-nodejs#149, MT-23076: support expires_at on the api token tools mailtrap-mcp#136, MT-23076: support api token expiration in create and reset mailtrap-php#75, MT-23076: support expires_at for api token create and reset mailtrap-ruby#122, MT-23076: support api token expiration mailtrap-java#68, MT-23076: expose api token expiration in create and reset requests mailtrap-dotnet#253, MT-23076: support api token expiration mailtrap-go#28, MT-23076: add --expires-at to tokens create and reset mailtrap-cli#12
• falcon PR railsware/falcon#10763
• spec PR MT-23076: document api token expiration mailtrap-openapi#51

Caveat: release/merge only after falcon deploys MT-23076 and zap_api_token_expiration is enabled in production.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8a8cfc42-7d17-406d-8a92-ae1cf7cd1589

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}