Create an inbox
Requires a full-scope key. Omit username to assign one in the form agent- plus 8 lowercase base32 characters. A required domain must belong to this tenant, be verified, and have receiving enabled. retention_days defaults to the plan maximum and must be from 1 through that maximum. The caller's mode sets test_mode and never changes. An address belongs to one inbox across tenants and modes.
Request body
| Parameter | Description |
|---|---|
usernamestring | Lowercase mailbox name. Omitted names are generated. |
domainrequiredstring | Verified tenant domain name with receiving enabled. |
display_namestring | Control characters are rejected. At most 64 characters. An empty name is allowed. Maximum length: 64. |
retention_daysinteger | Days to keep received mail. Defaults to the plan maximum. |
Full request schema and constraints
application/json- body
username?stringLowercase mailbox name. Omitted names are generated.
domain*stringVerified tenant domain name with receiving enabled.
display_name?stringControl characters are rejected. At most 64 characters. An empty name is allowed.
length <= 64retention_days?integerDays to keep received mail. Defaults to the plan maximum.
1 <= valueHeader parameters
| Parameter | Description |
|---|---|
Idempotency-Keystring | Repeated POST with the same key within 24 h returns the first response. Maximum length: 255. |
Full parameter schemas and constraints
Idempotency-Key?stringRepeated POST with the same key within 24 h returns the first response.
length <= 255AuthorizationBearer <token>API key: st_live_... or st_test_...
Inbox created.
application/json- response
id*stringaddress*stringusername*stringdomain*stringdisplay_name*stringlength <= 64retention_days*integer1 <= valuetest_mode*booleanMode of the key or dashboard session that created the inbox. It never changes.
created_at*stringdate-time