Mail API
Read a mailbox’s threads, messages and attachments, search them, label, archive, snooze and move them, manage the mailbox’s labels, filters and addresses, and write, send and schedule drafts. All endpoints are under https://api.cirrux.co/public_api/v1.
Reading needs email.read, changing mail and writing drafts needs email.write, and sending needs email.send. These endpoints take a user-scoped OAuth token or a workspace API key. A user token reaches every mailbox the person can open in the token’s workspace, shared mailboxes included. A key reaches only the mailboxes its admin chose when creating it: any other mailbox, and anything in it, answers 404 not_found as if it did not exist. A key can do everything on this page except change a mailbox’s addresses.
Every change goes through the same path as the mail app, so it shows up at once in the web app, on phones and over IMAP. To hear about new mail as it arrives instead of polling, use webhooks.
How mail is organized#
A mailbox holds threads, and a thread holds the emails of one conversation. Where an email is, and what it is tagged with, is a set of labels. Every mailbox has one system label of each type, and any number of custom ones.
| Field | Type | Description |
|---|---|---|
| inbox | location | In the inbox. |
| archive | location | Archived. |
| trash | location | In the trash. |
| junk | location | Marked as spam. |
| sent | system | Sent from this mailbox. Set when an email is sent. |
| draft | system | An unsent draft. Managed by the draft endpoints. |
| scheduled | system | A draft waiting to be sent later. Managed by send_at. |
| snoozed | system | Snoozed. Managed by the snooze endpoints. |
| user | custom | A label the user made, such as "Invoices". |
The four locations exclude one another: an email is in at most one of the inbox, the archive, the trash and spam. The verbs below (archive, trash, move and so on) keep that true for you, which is why they exist next to plain labeling. A sent email keeps its sent label wherever it goes.
In an email’s labels, a system label appears as its type (inbox) and a custom label as its name (Invoices). Where an endpoint takes a label, it takes either type, one of inbox, archive, trash, junk or auto_archive, or label_uuid for a custom label from GET /v1/mailboxes/{mailbox_uuid}/labels. auto_archive marks an inbox email to be archived after 30 days. It is a timer rather than a place, so it is not listed with the labels and you cannot move mail to it.
Lists are paginated with a cursor: follow next_cursor while has_more is true. Timestamps you send must carry an offset (Z or +02:00), and a time without one is refused rather than guessed.
The mailbox object#
| Field | Type | Required | Description |
|---|---|---|---|
| object | string | no | Always mailbox. |
| uuid | string | no | The mailbox. |
| primary_address | string | null | no | The address it sends from by default. |
| created_at | string | no | When it was created. |
| updated_at | string | null | no | When it last changed. |
The thread object#
| Field | Type | Required | Description |
|---|---|---|---|
| object | string | no | Always thread. |
| uuid | string | no | The thread. |
| mailbox_uuid | string | no | The mailbox it is in. |
| last_email_received_at | string | null | no | When the latest email arrived. Threads are listed newest first by this. |
| last_email_sent_at | string | null | no | When this mailbox last replied. |
| snooze_until | string | null | no | When the thread comes back, while any of its emails is snoozed. |
| snooze_condition | string | null | no | always, or if_no_reply to come back only when nobody has replied by then. |
| emails | array | no | Its emails, as email objects, oldest first. |
The email object#
| Field | Type | Required | Description |
|---|---|---|---|
| object | string | no | Always email. |
| uuid | string | no | The email. |
| mailbox_uuid | string | no | The mailbox it is in. |
| thread_uuid | string | no | The thread it belongs to. |
| from | array | no | A list of { "address": "…", "name": "…" } objects. name is optional. |
| to | array | no | A list of { "address": "…", "name": "…" } objects. name is optional. |
| cc | array | null | no | A list of { "address": "…", "name": "…" } objects. name is optional. |
| subject | string | no | The subject. |
| snippet | string | null | no | The start of the body, as plain text. |
| date | string | no | The date the message carries. |
| read_at | string | null | no | When it was read, null if unread. |
| flagged_at | string | null | no | When it was flagged (starred), null if not. |
| snooze_until | string | null | no | When it comes back, while snoozed. |
| snoozed_at | string | null | no | When it was snoozed. |
| unsnoozed_at | string | null | no | When it last came back from a snooze. |
| snooze_condition | string | null | no | always or if_no_reply. |
| labels | string[] | no | Its labels: a system label by type, a custom label by name. |
| attachments | array | no | Its attachments, as attachment objects. |
The body is not part of the email object. Fetch it as HTML, or the whole message as it arrived, with GET /v1/emails/{uuid}/get/body and /get/raw.
{
"object": "email",
"uuid": "5e6f7a8b-5555-4c9d-8e0f-000000000005",
"mailbox_uuid": "1c2d3e4f-3333-4a5b-8c6d-000000000003",
"thread_uuid": "7a8b9c0d-6666-4e1f-9a2b-000000000006",
"from": [{ "address": "jan@example.org", "name": "Jan de Vries" }],
"to": [{ "address": "jane@example.com", "name": "Jane" }],
"cc": [],
"subject": "Offsite planning",
"snippet": "Shall we book the venue for the 14th?",
"date": "2026-11-12T08:41:07.000Z",
"read_at": null,
"flagged_at": null,
"snooze_until": null,
"snoozed_at": null,
"unsnoozed_at": null,
"snooze_condition": null,
"labels": ["inbox", "Offsite"],
"attachments": [
{
"object": "attachment",
"uuid": "8b9c0d1e-7777-4f2a-8b3c-000000000007",
"filename": "venue.pdf",
"content_type": "application/pdf",
"file_size_bytes": 182344
}
]
}The draft object#
A draft is an email that has not been sent, with the fields you need to write it. It has no read_at, flagged_at or date.
| Field | Type | Required | Description |
|---|---|---|---|
| object | string | no | Always draft. |
| uuid | string | no | The draft. |
| mailbox_uuid | string | no | The mailbox it is in. |
| thread_uuid | string | no | The thread it belongs to. |
| in_reply_to_email_uuid | string | null | no | The email it replies to. |
| from | array | no | A list of { "address": "…", "name": "…" } objects. name is optional. |
| to | array | no | A list of { "address": "…", "name": "…" } objects. name is optional. |
| cc | array | null | no | A list of { "address": "…", "name": "…" } objects. name is optional. |
| bcc | array | null | no | A list of { "address": "…", "name": "…" } objects. name is optional. |
| subject | string | no | The subject. |
| snippet | string | null | no | The start of the body, as plain text. |
| body_html | string | null | no | The body as HTML. |
| body_text | string | null | no | The body as plain text. |
| labels | string[] | no | Includes draft, and scheduled once it has a send_at. |
| attachments | array | no | Its attachments, as attachment objects. |
| send_at | string | null | no | When it is scheduled to be sent. Null for a plain draft. |
| remind_at | string | null | no | When the sent email comes back to the inbox as a reminder. |
| remind_condition | string | null | no | always, or if_no_reply to remind only when nobody has replied. |
| created_at | string | no | When it was created. |
| updated_at | string | no | When it last changed. |
Mailboxes#
List mailboxes
/v1/mailboxesReturns the mailboxes the token may read in its workspace: the person’s own and shared ones, or for a workspace API key, the mailboxes it was created for. Not paginated. Scope email.read.
curl https://api.cirrux.co/public_api/v1/mailboxes \ -H "Authorization: Bearer $CIRRUX_TOKEN"
{
"object": "list",
"url": "/v1/mailboxes",
"has_more": false,
"data": [
{
"object": "mailbox",
"uuid": "1c2d3e4f-3333-4a5b-8c6d-000000000003",
"primary_address": "jane@example.com",
"created_at": "2025-03-02T10:14:51.120Z",
"updated_at": "2026-10-01T07:00:12.004Z"
}
]
}Get a mailbox
/v1/mailboxes/{mailbox_uuid}Returns one mailbox. Scope email.read.
Threads#
List threads
/v1/mailboxes/{mailbox_uuid}/threadsReturns a mailbox’s threads with their emails, newest first. Without label it lists every thread, whatever its location, trash and spam included. Scope email.read.
| Field | Type | Required | Description |
|---|---|---|---|
| label | string | no | Only threads with an email in this label: a system type (inbox, sent, draft or drafts, scheduled, archive, trash, junk or spam, snoozed) or a custom label’s uuid. |
| limit | number | no | Threads per page, 1 to 100. Defaults to 25. |
| cursor | string | no | The next_cursor of the previous page. |
curl -G https://api.cirrux.co/public_api/v1/mailboxes/1c2d3e4f-…/threads \ -d label=inbox \ -d limit=10 \ -H "Authorization: Bearer $CIRRUX_TOKEN"
Get a thread
/v1/threads/{thread_uuid}Returns one thread with all its emails. Scope email.read.
Archive, trash, mark read or flag a thread
/v1/threads/{thread_uuid}/{verb}Does to a whole conversation what the same button in the mail app does, and returns the thread. No body. Drafts in the thread are left alone. Every verb is safe to repeat. Scope email.write.
| Field | Type | Description |
|---|---|---|
| archive | verb | Archives every email. unarchive puts them back in the inbox. |
| trash | verb | Moves every email to the trash. untrash puts each back where it was before. |
| spam | verb | Marks the thread as spam. unspam puts each email back where it was before. |
| read | verb | Marks every email read. unread marks the last received one unread. |
| flag | verb | Flags the latest email. unflag clears every flag in the thread. |
curl -X POST https://api.cirrux.co/public_api/v1/threads/7a8b9c0d-…/archive \ -H "Authorization: Bearer $CIRRUX_TOKEN"
Move a thread
/v1/threads/{thread_uuid}/moveMoves every email to one label, taking it out of the others, and returns the thread. Moving to trash or junk is the same as trashing or marking as spam. Scope email.write.
| Field | Type | Required | Description |
|---|---|---|---|
| type | string | no | inbox, archive, trash or junk. |
| label_uuid | string | no | Or a custom label. Send exactly one of the two. |
curl https://api.cirrux.co/public_api/v1/threads/7a8b9c0d-…/move \
-H "Authorization: Bearer $CIRRUX_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "label_uuid": "3d4e5f6a-…" }'Label or unlabel a thread
/v1/threads/{thread_uuid}/labels/v1/threads/{thread_uuid}/labels/{label}Adds a label to the emails in the thread that were received rather than sent, with type or label_uuid in the body as for a move, or takes one off every email that has it, with the type or uuid in the path. Returns the thread. Scope email.write.
Snooze a thread
/v1/threads/{thread_uuid}/snooze/v1/threads/{thread_uuid}/unsnoozeTakes the thread out of the inbox until a time in the future, when it comes back unread. Drafts in the thread are skipped. unsnooze brings it back now, and takes no body. Both return the thread. Scope email.write.
| Field | Type | Required | Description |
|---|---|---|---|
| until | string | yes | When it comes back: an ISO-8601 timestamp with an offset, in the future. |
| condition | string | no | always (the default), or if_no_reply to bring it back only when nobody has replied by then. |
curl https://api.cirrux.co/public_api/v1/threads/7a8b9c0d-…/snooze \
-H "Authorization: Bearer $CIRRUX_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "until": "2026-11-16T08:00:00+01:00", "condition": "if_no_reply" }'Emails#
Get an email
/v1/emails/{email_uuid}Returns one email. Scope email.read.
Get an email's body or raw message
/v1/emails/{email_uuid}/get/body/v1/emails/{email_uuid}/get/rawbody returns the body as text/html. raw returns the whole message as it arrived (RFC 5322, headers and attachments included) as application/octet-stream. Neither is JSON. Scope email.read.
curl https://api.cirrux.co/public_api/v1/emails/5e6f7a8b-…/get/raw \ -H "Authorization: Bearer $CIRRUX_TOKEN" \ -o message.eml
Mark an email read or flagged
/v1/emails/{email_uuid}Sets when the email was read or flagged, and returns it. A timestamp marks it, null clears it, and a field you leave out stays as it is. A timestamp cannot be in the future or before the email’s date. Scope email.write.
| Field | Type | Required | Description |
|---|---|---|---|
| read_at | string | null | no | When it was read, or null for unread. |
| flagged_at | string | null | no | When it was flagged, or null to unflag. |
curl https://api.cirrux.co/public_api/v1/emails/5e6f7a8b-… \
-H "Authorization: Bearer $CIRRUX_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "read_at": "2026-11-13T09:30:00Z" }'Archive, trash or mark an email as spam
/v1/emails/{email_uuid}/{verb}The same verbs as for a thread, for one email: archive and unarchive, trash and untrash, spam and unspam. No body, and each returns the email. Trashing or marking as spam remembers the email’s labels, and undoing it puts them back (or the inbox when none of them exists any more). A sent email cannot be marked as spam. Scope email.write.
Move an email
/v1/emails/{email_uuid}/moveMoves the email to one label, with type or label_uuid as for a thread, and returns it. Scope email.write.
Label or unlabel an email
/v1/emails/{email_uuid}/labels/v1/emails/{email_uuid}/labels/{label}Adds a label, with type or label_uuid in the body, or removes one, with the type or uuid in the path. Returns the email. Adding a second location (say inbox to an archived email) is refused with 422 incoherent_label_combination: use the verb or a move instead. Removing an email’s last location archives it, or puts it in the inbox when it was the archive you removed, so mail never ends up nowhere. Scope email.write.
curl https://api.cirrux.co/public_api/v1/emails/5e6f7a8b-…/labels \
-H "Authorization: Bearer $CIRRUX_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "type": "auto_archive" }'Snooze an email
/v1/emails/{email_uuid}/snooze/v1/emails/{email_uuid}/unsnoozeThe same as snoozing a thread, for one email, with the same until and condition. A draft cannot be snoozed: give it a remind_at instead. Scope email.write.
Attachments#
Get an attachment
/v1/email_attachments/{attachment_uuid}Returns the attachment object: uuid, filename, content_type and file_size_bytes. Scope email.read.
Download an attachment
/v1/email_attachments/{attachment_uuid}/getReturns the file’s bytes in data, base64url-encoded without padding. Scope email.read.
{
"uuid": "8b9c0d1e-7777-4f2a-8b3c-000000000007",
"size": 182344,
"data": "JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9UeXBl…"
}To attach it to a draft, or save it to Drive, pass its uuid instead of downloading and uploading it: see attachments on a draft below, and attachment_uuid in the Drive API.
Search#
Search threads or emails
/v1/search/threads/v1/search/emailsSearches every mailbox the token can read, or one, with the same search language as the mail app. threads returns thread objects and emails returns email objects, both paginated. Trash and spam are left out unless the query asks for them with in:trash or in:spam. Scope email.read.
| Field | Type | Required | Description |
|---|---|---|---|
| q | string | yes | The query, up to 2,000 characters. |
| mailbox_uuid | string | no | Search only this mailbox. |
| label_uuid | string | no | Search only this label, and so only the mailbox it belongs to. |
| limit | number | no | Results per page, 1 to 100. Defaults to 25. |
| cursor | string | no | The next_cursor of the previous page. |
Words are matched against the subject, body and addresses, and every term must match. Group with brackets, combine with OR, exclude with a leading -, and quote a phrase.
| Field | Type | Description |
|---|---|---|
| from: to: cc: bcc: | text | An address or name. |
| subject: body: | text | One part of the message only. |
| is: | state | unread, read, starred, unstarred, replied. |
| has: | presence | attachment |
| in: | place | inbox, sent, drafts, scheduled, archive, trash, spam, snoozed, starred. |
| label: | text | A custom label by name: label:"Project X". |
| after: before: | date | YYYY-MM-DD. after: includes the day, before: does not. |
| larger: smaller: | size | Bytes, or with K, M or G: larger:10M. |
curl -G https://api.cirrux.co/public_api/v1/search/threads \ --data-urlencode 'q=from:jan@example.org has:attachment after:2026-11-01' \ -H "Authorization: Bearer $CIRRUX_TOKEN"
{
"object": "list",
"url": "/v1/search/threads",
"query": "from:jan@example.org has:attachment after:2026-11-01",
"has_more": false,
"data": [ { "object": "thread", … } ]
}Drafts and sending#
Create a draft
/v1/draftsCreates a draft and returns it. It appears in the mail app’s Drafts at once, where the person can open and finish it. Write the body in markdown and let Cirrux build the message, or hand over a complete MIME message. Scope email.write.
| Field | Type | Required | Description |
|---|---|---|---|
| mailbox_uuid | string | yes | The mailbox to write it in. |
| body_format | string | yes | markdown or mime. |
| markdown | string | no | The body, for markdown. Required there. |
| mime | string | no | A complete RFC 5322 message, for mime. Required there. Its From must be one of the mailbox’s addresses. |
| subject | string | no | The subject. |
| to | array | no | A list of { "address": "…", "name": "…" } objects. name is optional. |
| cc | array | no | A list of { "address": "…", "name": "…" } objects. name is optional. |
| bcc | array | no | A list of { "address": "…", "name": "…" } objects. name is optional. |
| from | string | no | Which of the mailbox’s addresses to send from. Defaults to its primary address, or for a reply, the address the original was sent to. |
| in_reply_to_email_uuid | string | no | Make it a reply to this email. It joins that thread, and whatever you leave out (recipients, subject) is filled in as the mail app would. |
| reply_all | boolean | no | With a reply, address everyone on the original rather than only its sender. |
| forward_email_uuid | string | no | Make it a forward of this email, with its attachments. Not together with a reply. |
| quote_original | boolean | no | Whether a reply quotes the original, or a forward includes it. Defaults to true. |
| signature | string | no | A signature’s uuid, or default for the mailbox’s default one. Left out, the draft has no signature. |
| attachments | array | no | Up to 10 files already in Cirrux, each { "attachment_uuid": "…" } for an email attachment or { "drive_file_uuid": "…" } for a Drive file (which also needs drive.read). Copied without passing through you. At most 25 MB a file and 35 MB for the whole email. |
| remind_at | string | no | Bring the sent email back to the inbox at this time, as a reminder. In the future, with an offset. |
| remind_condition | string | no | always (the default) or if_no_reply. |
from, reply_all, forward_email_uuid and signature only apply to markdown drafts: a MIME message carries its own headers. A reply or forward must be created in the mailbox the original is in, and the error says which one that is.
curl https://api.cirrux.co/public_api/v1/drafts \
-H "Authorization: Bearer $CIRRUX_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"mailbox_uuid": "1c2d3e4f-…",
"body_format": "markdown",
"in_reply_to_email_uuid": "5e6f7a8b-…",
"markdown": "The 14th works for me. **Booking it now.**",
"signature": "default"
}'Change a draft
/v1/drafts/{draft_uuid}Changes the fields you send and returns the draft. A field you leave out stays as it is, and an empty recipient list clears it. A new markdown replaces what was written and keeps the signature and the quoted original below it. Any other field is refused with 400 invalid_body. A draft scheduled to be sent cannot be changed. Scope email.write.
| Field | Type | Required | Description |
|---|---|---|---|
| to | array | no | A list of { "address": "…", "name": "…" } objects. name is optional. |
| cc | array | no | A list of { "address": "…", "name": "…" } objects. name is optional. |
| bcc | array | no | A list of { "address": "…", "name": "…" } objects. name is optional. |
| subject | string | no | A new subject. |
| markdown | string | no | A new body. |
| add_attachments | array | no | Files to add, as attachments on create. |
| remove_attachment_uuids | string[] | no | The draft’s own attachments to take off. |
Delete a draft
/v1/drafts/{draft_uuid}Deletes a draft and returns 204. Scope email.write.
Send or schedule a draft
/v1/drafts/{draft_uuid}/sendSends the draft now and returns the sent email. With send_at it is scheduled instead, and the response is the draft with its send_at: it goes out at that time, and sending it again with a new send_at reschedules it. A workspace API key sends in the mailbox owner’s name, as the web app would. The workspace and mailbox sending limits apply. The body is optional. Scope email.send.
| Field | Type | Required | Description |
|---|---|---|---|
| send_at | string | no | Send it later, at this time. In the future, with an offset. |
| remind_at | string | null | no | A reminder, as on create. Replaces the one the draft has, and null removes it. |
| remind_condition | string | no | As on create. |
curl https://api.cirrux.co/public_api/v1/drafts/0d1e2f3a-…/send \
-H "Authorization: Bearer $CIRRUX_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "send_at": "2026-11-16T08:30:00+01:00" }'To cancel a scheduled send, delete the draft. A 429 rate_limited from a send carries Retry-After, and reason and limit_type in the body say which limit was reached.
List signatures
/v1/mailboxes/{mailbox_uuid}/signaturesReturns the mailbox’s signatures in the order the mail app shows them, each with uuid, name, is_default, position and the signature as html. Read only. Scope email.read.
Labels#
| Field | Type | Required | Description |
|---|---|---|---|
| object | string | no | Always label. |
| uuid | string | no | The label. |
| name | string | no | Its name. |
| type | string | no | A system type such as inbox, or user for a custom label. |
| color | string | null | no | Its color. |
| description | string | null | no | Its description. |
| is_visible | boolean | no | Whether the mail app shows it in the sidebar. |
| position | number | no | Sort position. |
List labels
/v1/mailboxes/{mailbox_uuid}/labelsReturns the mailbox’s system and custom labels, in the order of the mail app’s sidebar. Not paginated. Scope email.read.
Create a label
/v1/mailboxes/{mailbox_uuid}/labelsCreates a custom label and returns it with 201. When the mailbox already has one by that name, you get that one back. Scope email.write.
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | yes | The name. |
Rename or delete a label
/v1/mailboxes/{mailbox_uuid}/labels/{label_uuid}/v1/mailboxes/{mailbox_uuid}/labels/{label_uuid}Renames a custom label with name and returns it, or deletes it with 204. System labels cannot be renamed or deleted. Scope email.write.
Filters#
A filter runs on every email that arrives in the mailbox: when its condition_ast matches, its actions run. Filters run in priority order, and one with stop_processing stops the ones after it.
| Field | Type | Required | Description |
|---|---|---|---|
| object | string | no | Always email_filter_rule. |
| uuid | string | no | The filter. |
| mailbox_uuid | string | no | The mailbox it runs in. |
| name | string | no | Its name. |
| description | string | null | no | Its description. |
| status | string | no | active or inactive. |
| priority | number | no | The order it runs in, lowest first. |
| stop_processing | boolean | no | Whether later filters are skipped after it matches. |
| condition_ast | object | no | What it matches, as a tree. See below. |
| actions | array | no | What it does. See below. |
| match_count | number | no | How many emails it has matched. |
| last_matched_at | string | null | no | When it last matched. |
| created_at | string | no | When it was created. |
| updated_at | string | null | no | When it last changed. |
Conditions and actions
A condition is a node with a type. and and or take children, not takes one child, and all matches every email.
| Field | Type | Description |
|---|---|---|
| contains | field, value | field is from, to, cc, bcc, subject, body, message_id or text. |
| equals | field, value | The same fields, without message_id and text. |
| dateafter datebefore | field, value | field is received_at or created_at, value a date such as 2026-01-15. |
| flag | field, value | field is seen, answered, flagged or deleted, value a boolean. |
| hasattachment isreply isnewsletter fromcontact | value | A boolean value. |
| sizegreaterthan sizelessthan | bytes | A whole number of bytes. |
| fromcontactgroup | contact_group_uuid | From someone in this contact group. |
Each action is an object with a type: add_label (with label_uuid), skip_inbox, mark_read, flag, archive, auto_archive, delete (to the trash), destroy (deleted for good), forward (with forwarding_address_uuid) or never_mark_as_spam.
List or get filters
/v1/mailboxes/{mailbox_uuid}/filters/v1/mailboxes/{mailbox_uuid}/filters/{filter_uuid}Returns the mailbox’s filters in the order they run, or one filter. Scope email.read.
Create a filter
/v1/mailboxes/{mailbox_uuid}/filtersCreates a filter and returns it with 201. Scope email.write.
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | yes | Its name. |
| condition_ast | object | yes | What it matches. |
| actions | array | no | What it does. Defaults to none. |
| description | string | no | A description. |
| status | string | no | active (the default) or inactive. |
| priority | number | no | Its place in the order. Defaults to 0. |
| stop_processing | boolean | no | Defaults to false. |
curl https://api.cirrux.co/public_api/v1/mailboxes/1c2d3e4f-…/filters \
-H "Authorization: Bearer $CIRRUX_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Invoices",
"condition_ast": {
"type": "and",
"children": [
{ "type": "contains", "field": "from", "value": "billing@" },
{ "type": "hasattachment", "value": true }
]
},
"actions": [
{ "type": "add_label", "label_uuid": "3d4e5f6a-…" },
{ "type": "skip_inbox" }
]
}'Change or delete a filter
/v1/mailboxes/{mailbox_uuid}/filters/{filter_uuid}/v1/mailboxes/{mailbox_uuid}/filters/{filter_uuid}Changes the fields you send, the same ones as on create, and returns the filter. Or deletes it with 204. Scope email.write.
Addresses#
The addresses a mailbox receives mail at and can send from: its primary address and its aliases. A workspace API key can list them but not change them, which answers 403 forbidden.
| Field | Type | Required | Description |
|---|---|---|---|
| object | string | no | Always mailbox_address. |
| uuid | string | no | The address. |
| mailbox_uuid | string | no | The mailbox it delivers to. |
| address | string | no | The full address, such as sales@example.com. |
| local_part | string | no | The part before the @. |
| domain | string | no | The domain. |
| is_primary | boolean | no | The address the mailbox sends from by default. It cannot be deactivated or deleted. |
| deactivated_at | string | null | no | Set while it is switched off: mail to it is no longer delivered. |
| auto_created_at | string | null | no | Set when it was added by itself, the first time mail for it came in through a catch-all. |
| created_at | string | no | When it was added. |
List addresses
/v1/mailboxes/{mailbox_uuid}/addressesReturns every address of the mailbox. Scope email.read.
Add an address
/v1/mailboxes/{mailbox_uuid}/addressesAdds an alias on one of the workspace’s domains and returns it with 201. Needs a user-scoped token and the right to manage the mailbox’s addresses. Scope email.write.
| Field | Type | Required | Description |
|---|---|---|---|
| address | string | yes | The full address, such as sales@example.com. |
Deactivate or make an address primary
/v1/mailboxes/{mailbox_uuid}/addresses/{address_uuid}Switches an address off or back on, or makes it the primary one, and returns it. Send at least one of the two. To change the primary address, make another one primary. Scope email.write.
| Field | Type | Required | Description |
|---|---|---|---|
| deactivated | boolean | no | true to switch it off, false to switch it back on. |
| is_primary | boolean | no | Only true. Not together with deactivating. |
Delete an address
/v1/mailboxes/{mailbox_uuid}/addresses/{address_uuid}Deletes an alias and returns 204. The primary address cannot be deleted. Scope email.write.
Errors#
Mail error codes
On top of the shared errors, mail endpoints can return:
| Status | error | When |
|---|---|---|
| 400 | invalid_body | A required field is missing or has the wrong type, both or neither of type and label_uuid were sent, or a draft change has a field it does not take. |
| 400 | invalid_format | The format in /get/{format} is not body or raw. |
| 402 | subscription_inactive | The workspace needs an active subscription to send mail. |
| 403 | forbidden | A workspace API key tried to change an address, or you may not manage this mailbox’s addresses. |
| 404 | not_found | The mailbox, thread, email, attachment, label, filter or address does not exist or is not yours to use. Also when an email has no body or raw message stored. |
| 404 | signature_not_found | The signature named in a draft is not in the mailbox, or the mailbox has no default one. |
| 404 | attachment_not_found | A file in attachments or add_attachments names an email attachment you cannot read. drive_file_not_found is its Drive twin. |
| 409 | address_taken | The address is already in use. |
| 422 | invalid_value | A value is out of range: a timestamp without an offset, a snooze or send_at in the past, an unknown label type, a filter condition or action it cannot read, an address that is not on a workspace domain, a From that is not the mailbox’s, or a draft that cannot be sent as it is (no recipients, an unverified sending domain). |
| 422 | invalid_state | The email cannot take this change: a draft (use the draft endpoints), a sent email marked as spam, auto_archive on an email outside the inbox, or a thread with nothing to snooze. |
| 422 | incoherent_label_combination | Adding this label would put the email in two locations. Archive, trash or move it instead. |
| 422 | protected_label | System labels cannot be renamed or deleted. |
| 422 | mailbox_mismatch | The email you reply to or forward is in another mailbox. mailbox_uuid in the body says which. |
| 422 | not_a_draft | The uuid names an email that is not a draft. |
| 422 | already_scheduled | The draft is scheduled to be sent, so it cannot be changed or sent now. |
| 422 | too_large | An attached file is over 25 MB, or together they are over 35 MB. Other refusals of a file: not_uploaded, infected, trashed. |
| 422 | invalid_query | The search query is missing or cannot be read. The description says what to fix. |
| 429 | rate_limited | A send reached the workspace or mailbox sending limit. Wait for Retry-After seconds. |
| 504 | search_timeout | The search took too long. Narrow the query. |