An inbox is an email address that can send and receive. Its id is the address — support@carlyemail.com — not an opaque handle, so you never have to look one up to know where mail goes.

curl -X POST https://api.carlyemail.com/v0/inboxes \
  -H "Authorization: Bearer $CARLYEMAIL_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"username": "support", "display_name": "Support"}'

Omit username and one is generated. Omit domain and you get the default: carlyemail.com for verified organizations, agents.carlyemail.com for unverified ones.

Usernames are globally unique per domain

Two organizations cannot both hold support@carlyemail.com — it is one address on one domain, and mail to it has to go somewhere unambiguous. A collision returns 409 username_unavailable. Bring your own domain if you want a name somebody else has taken; see custom domains.

Deleting

Deleting an inbox deletes its messages. Mail arriving for a deleted address is acknowledged and dropped rather than retried, because retrying an address that does not exist can never succeed.