Inboxes

An inbox is an email address your agent owns. Creating one is a single API call; there is nothing to configure on a mail server.

Create

• username: the local part, lowercase letters, digits, dots, dashes and underscores. Random when empty.
• domain: a verified custom domain of your organization. The platform shared domain when empty.
• display_name: the name shown to recipients, up to 200 characters.
• client_id: your own identifier. Repeating it returns the existing inbox with status 200 instead of 201, so create calls are safe to retry.

curl -s -X POST https://api.162-55-213-24.sslip.io/v0/inboxes \
  -H "Authorization: Bearer $MAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "billing", "domain": "agents.your-domain.eu", "display_name": "Billing agent", "client_id": "billing"}'

Errors: 403 limit_exceeded when the plan's inbox limit is reached, 403 domain_not_verified when the domain is not verified for your organization, 409 already_exists when the address is taken, 409 address_quarantined when it belonged to an inbox deleted less than 90 days ago.

Identify an inbox

Paths take the inbox email address as {inbox}, for example /v0/inboxes/billing@agents.your-domain.eu. URL encode it when your HTTP client does not do it for you.

Delete

Deleting an inbox deletes all its threads, messages and attachments, including the stored raw messages and files. It cannot be undone. The address is then reserved for 90 days: no organization can create it again in that window (409 address_quarantined), so nobody receives mail meant for the previous owner.

Endpoints