Docs

Inboxes

Create, list, rename and delete inboxes. One inbox per agent, per user or per task.

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

curl -s -X POST https://api.mueslimail.com/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

POST/v0/inboxes

Create an inbox (repeat client_id to get the same inbox)

Body (CreateInbox)

Name	Type	Notes
`username`	string	pattern ^[a-z0-9]([a-z0-9._-]{0,62}[a-z0-9])?$
`domain`	string
`display_name`	string	max length 200
`client_id`	string	pattern ^[A-Za-z0-9._~-]{1,256}$

Responses

200 Existing inbox for this client_id: Inbox
201 Created: Inbox
403 Error envelope: Error
409 Error envelope: Error

GET/v0/inboxes

List inboxes, newest first

Parameters

Name	Type	Notes
`limit`	integer	in query, min 1, max 100, default 20
`page_token`	string	in query

Responses

200 OK: InboxList

GET/v0/inboxes/{inbox}

Get an inbox

Parameters

Name	Type	Notes
`inbox`	string (email)	in path, required

Responses

200 OK: Inbox
404 Error envelope: Error

PATCH/v0/inboxes/{inbox}

Update the display name, the signature, or the support intake of an inbox

Parameters

Name	Type	Notes
`inbox`	string (email)	in path, required

Body

Name	Type	Notes
`display_name`	string	max length 200
`ticket_intake`	boolean	New threads on this inbox become tickets in the support queue.
`signature_html`	string	HTML signature of this address. Empty string removes it., max length 20000

Responses

200 OK: Inbox

DELETE/v0/inboxes/{inbox}

Delete an inbox and all its mail

Parameters

Name	Type	Notes
`inbox`	string (email)	in path, required

Responses

204 Deleted
404 Error envelope: Error

Inbox object

Name	Type	Notes
`id`	string (uuid)
`inbox_id`	string (email)
`email`	string (email)
`display_name`	string
`client_id`	string
`ticket_intake`	boolean	New threads on this inbox become tickets.
`sending_paused_at`	string (date-time)	Set when the breaker paused sending for this inbox; null when only the organization is paused, which sending_health reports in paused_scope. An operator resumes it.
`sending_paused_reason`	string
`sending_health`	SendingHealth
`signature_html`	string	The signature of this address, HTML, applied to every message composed after it was written. Changing it never rewrites a draft that already exists (the rule of Proton): a draft keeps the signature of its own moment.
`group`	GroupRef
`grants_count`	integer	How many people hold access directly on this inbox. Null unless the caller is the owner or an admin.
`created_at`	string (date-time)
`updated_at`	string (date-time)

SendingHealth object

Name	Type	Notes
`state`	ok \| paused	paused means sending from this inbox is refused with 403 sending_paused.
`paused_scope`	string	What paused sending: inbox, organization, or empty while state is ok. A send is refused by both scopes, so this is what tells them apart. Not an enum because the empty string is a value, and a validator that rejected it would fail on every healthy inbox.
`paused_at`	string (date-time)	When the breaker paused the inbox or its organization; null while state is ok.
`paused_reason`	string	The same sentence the 403 sending_paused carries, naming the window and the limit that was crossed, and the counts at the moment of the pause.
`window_hours`	integer	Length of the rolling window the counts cover.
`sends`	integer	Messages that reached a final outcome (accepted or rejected) in the window.
`hard_bounces`	integer	Permanent rejections at send time plus bounces reported later by a delivery status notification.
`complaints`	integer	Spam complaints reported through the feedback loop.
`bounce_rate`	number	hard_bounces divided by sends, 0 when sends is 0.
`complaint_rate`	number	complaints divided by sends, 0 when sends is 0.
`thresholds`	SendingThresholds

SendingThresholds object

Name	Type	Notes
`max_bounce_rate`	number	Hard bounce rate above which sending pauses.
`max_complaint_rate`	number	Complaint rate above which sending pauses, once min_complaint_sends is reached.
`min_sends`	integer	Sends needed in the window before the bounce rate applies.
`min_complaint_sends`	integer	Sends needed before the complaint rate applies; below it the limit is a count.
`small_sender_complaints`	integer	Complaints in the window that pause sending below min_complaint_sends.