inboxes

Create an inbox

local_part becomes the address local_part@cherami.to. The address is permanent: it can't be renamed or moved to another domain. To move an agent to a new address, see Change your agent's email address.

name identifies the inbox within the account and isn't shown to recipients; sender_name is the display name recipients see on its mail. Both are optional, can be edited later and need not be unique.

Recover creation

Include an idempotency_key to make a retry safe. If the response is lost or you get a 5xx, repeat the request with the same key and the original payload within 24 hours of your first attempt: a match returns 200 with replayed: true and the inbox as it is now, and creates nothing new.

A request refused with 400, address_unavailable or inbox_limit_reached leaves its key unused. Use each key for one inbox, and don't switch to a new key or another address to get past an uncertain result.

After 24 hours, or without a key, list inboxes and look for the address before creating again: an unkeyed repeat of a creation that succeeded returns 409 address_unavailable.

post/v1/inboxes

Request

  • Base URL: https://cherami.to
  • URL: https://cherami.to/v1/inboxes
  • Auth: HTTP bearer

Request body

local_partstring required

The part before @cherami.to, lowercased: 1–64 letters, digits, hyphens or underscores, starting and ending with a letter or digit. Taken, reserved and retired addresses are unavailable.

namestring nullable

Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters.

sender_namestring nullable

Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters.

idempotency_keystring

Your unique value for this one operation. Save it with the exact request before sending; repeating that request with the same key within 24 hours returns what the first one did instead of acting again.

Response

A retry matched an earlier request: this is that request's result as it is now. Nothing new was created or sent.

idstring required

Cherami resource ID.

local_partstring required
addressstring required
namestring nullable required
sender_namestring nullable required
created_atstring date-time required

UTC timestamp with milliseconds.

replayedtrue required

true when a retry matched an earlier request: the result is that request's, and nothing new was created or sent.

idempotency_expires_atstring date-time required

When the key stops protecting retries.

Changes

No recorded changes to this operation across all 1 revision of this API.