cirrux

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.

FieldTypeDescription
inboxlocationIn the inbox.
archivelocationArchived.
trashlocationIn the trash.
junklocationMarked as spam.
sentsystemSent from this mailbox. Set when an email is sent.
draftsystemAn unsent draft. Managed by the draft endpoints.
scheduledsystemA draft waiting to be sent later. Managed by send_at.
snoozedsystemSnoozed. Managed by the snooze endpoints.
usercustomA 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#

FieldTypeRequiredDescription
objectstringnoAlways mailbox.
uuidstringnoThe mailbox.
primary_addressstring | nullnoThe address it sends from by default.
created_atstringnoWhen it was created.
updated_atstring | nullnoWhen it last changed.

The thread object#

FieldTypeRequiredDescription
objectstringnoAlways thread.
uuidstringnoThe thread.
mailbox_uuidstringnoThe mailbox it is in.
last_email_received_atstring | nullnoWhen the latest email arrived. Threads are listed newest first by this.
last_email_sent_atstring | nullnoWhen this mailbox last replied.
snooze_untilstring | nullnoWhen the thread comes back, while any of its emails is snoozed.
snooze_conditionstring | nullnoalways, or if_no_reply to come back only when nobody has replied by then.
emailsarraynoIts emails, as email objects, oldest first.

The email object#

FieldTypeRequiredDescription
objectstringnoAlways email.
uuidstringnoThe email.
mailbox_uuidstringnoThe mailbox it is in.
thread_uuidstringnoThe thread it belongs to.
fromarraynoA list of { "address": "…", "name": "…" } objects. name is optional.
toarraynoA list of { "address": "…", "name": "…" } objects. name is optional.
ccarray | nullnoA list of { "address": "…", "name": "…" } objects. name is optional.
subjectstringnoThe subject.
snippetstring | nullnoThe start of the body, as plain text.
datestringnoThe date the message carries.
read_atstring | nullnoWhen it was read, null if unread.
flagged_atstring | nullnoWhen it was flagged (starred), null if not.
snooze_untilstring | nullnoWhen it comes back, while snoozed.
snoozed_atstring | nullnoWhen it was snoozed.
unsnoozed_atstring | nullnoWhen it last came back from a snooze.
snooze_conditionstring | nullnoalways or if_no_reply.
labelsstring[]noIts labels: a system label by type, a custom label by name.
attachmentsarraynoIts 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.

FieldTypeRequiredDescription
objectstringnoAlways draft.
uuidstringnoThe draft.
mailbox_uuidstringnoThe mailbox it is in.
thread_uuidstringnoThe thread it belongs to.
in_reply_to_email_uuidstring | nullnoThe email it replies to.
fromarraynoA list of { "address": "…", "name": "…" } objects. name is optional.
toarraynoA list of { "address": "…", "name": "…" } objects. name is optional.
ccarray | nullnoA list of { "address": "…", "name": "…" } objects. name is optional.
bccarray | nullnoA list of { "address": "…", "name": "…" } objects. name is optional.
subjectstringnoThe subject.
snippetstring | nullnoThe start of the body, as plain text.
body_htmlstring | nullnoThe body as HTML.
body_textstring | nullnoThe body as plain text.
labelsstring[]noIncludes draft, and scheduled once it has a send_at.
attachmentsarraynoIts attachments, as attachment objects.
send_atstring | nullnoWhen it is scheduled to be sent. Null for a plain draft.
remind_atstring | nullnoWhen the sent email comes back to the inbox as a reminder.
remind_conditionstring | nullnoalways, or if_no_reply to remind only when nobody has replied.
created_atstringnoWhen it was created.
updated_atstringnoWhen it last changed.

Mailboxes#

List mailboxes

GET/v1/mailboxes

Returns 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

GET/v1/mailboxes/{mailbox_uuid}

Returns one mailbox. Scope email.read.

Threads#

List threads

GET/v1/mailboxes/{mailbox_uuid}/threads

Returns 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.

FieldTypeRequiredDescription
labelstringnoOnly 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.
limitnumbernoThreads per page, 1 to 100. Defaults to 25.
cursorstringnoThe 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

GET/v1/threads/{thread_uuid}

Returns one thread with all its emails. Scope email.read.

Archive, trash, mark read or flag a thread

POST/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.

FieldTypeDescription
archiveverbArchives every email. unarchive puts them back in the inbox.
trashverbMoves every email to the trash. untrash puts each back where it was before.
spamverbMarks the thread as spam. unspam puts each email back where it was before.
readverbMarks every email read. unread marks the last received one unread.
flagverbFlags 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

POST/v1/threads/{thread_uuid}/move

Moves 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.

FieldTypeRequiredDescription
typestringnoinbox, archive, trash or junk.
label_uuidstringnoOr 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

POST/v1/threads/{thread_uuid}/labels
DELETE/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

POST/v1/threads/{thread_uuid}/snooze
POST/v1/threads/{thread_uuid}/unsnooze

Takes 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.

FieldTypeRequiredDescription
untilstringyesWhen it comes back: an ISO-8601 timestamp with an offset, in the future.
conditionstringnoalways (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

GET/v1/emails/{email_uuid}

Returns one email. Scope email.read.

Get an email's body or raw message

GET/v1/emails/{email_uuid}/get/body
GET/v1/emails/{email_uuid}/get/raw

body 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

POST/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.

FieldTypeRequiredDescription
read_atstring | nullnoWhen it was read, or null for unread.
flagged_atstring | nullnoWhen 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

POST/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

POST/v1/emails/{email_uuid}/move

Moves 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

POST/v1/emails/{email_uuid}/labels
DELETE/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

POST/v1/emails/{email_uuid}/snooze
POST/v1/emails/{email_uuid}/unsnooze

The 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

GET/v1/email_attachments/{attachment_uuid}

Returns the attachment object: uuid, filename, content_type and file_size_bytes. Scope email.read.

Download an attachment

GET/v1/email_attachments/{attachment_uuid}/get

Returns 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 threads or emails

GET/v1/search/threads
GET/v1/search/emails

Searches 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.

FieldTypeRequiredDescription
qstringyesThe query, up to 2,000 characters.
mailbox_uuidstringnoSearch only this mailbox.
label_uuidstringnoSearch only this label, and so only the mailbox it belongs to.
limitnumbernoResults per page, 1 to 100. Defaults to 25.
cursorstringnoThe 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.

FieldTypeDescription
from: to: cc: bcc:textAn address or name.
subject: body:textOne part of the message only.
is:stateunread, read, starred, unstarred, replied.
has:presenceattachment
in:placeinbox, sent, drafts, scheduled, archive, trash, spam, snoozed, starred.
label:textA custom label by name: label:"Project X".
after: before:dateYYYY-MM-DD. after: includes the day, before: does not.
larger: smaller:sizeBytes, 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

POST/v1/drafts

Creates 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.

FieldTypeRequiredDescription
mailbox_uuidstringyesThe mailbox to write it in.
body_formatstringyesmarkdown or mime.
markdownstringnoThe body, for markdown. Required there.
mimestringnoA complete RFC 5322 message, for mime. Required there. Its From must be one of the mailbox’s addresses.
subjectstringnoThe subject.
toarraynoA list of { "address": "…", "name": "…" } objects. name is optional.
ccarraynoA list of { "address": "…", "name": "…" } objects. name is optional.
bccarraynoA list of { "address": "…", "name": "…" } objects. name is optional.
fromstringnoWhich 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_uuidstringnoMake 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_allbooleannoWith a reply, address everyone on the original rather than only its sender.
forward_email_uuidstringnoMake it a forward of this email, with its attachments. Not together with a reply.
quote_originalbooleannoWhether a reply quotes the original, or a forward includes it. Defaults to true.
signaturestringnoA signature’s uuid, or default for the mailbox’s default one. Left out, the draft has no signature.
attachmentsarraynoUp 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_atstringnoBring the sent email back to the inbox at this time, as a reminder. In the future, with an offset.
remind_conditionstringnoalways (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

PATCH/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.

FieldTypeRequiredDescription
toarraynoA list of { "address": "…", "name": "…" } objects. name is optional.
ccarraynoA list of { "address": "…", "name": "…" } objects. name is optional.
bccarraynoA list of { "address": "…", "name": "…" } objects. name is optional.
subjectstringnoA new subject.
markdownstringnoA new body.
add_attachmentsarraynoFiles to add, as attachments on create.
remove_attachment_uuidsstring[]noThe draft’s own attachments to take off.

Delete a draft

DELETE/v1/drafts/{draft_uuid}

Deletes a draft and returns 204. Scope email.write.

Send or schedule a draft

POST/v1/drafts/{draft_uuid}/send

Sends 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.

FieldTypeRequiredDescription
send_atstringnoSend it later, at this time. In the future, with an offset.
remind_atstring | nullnoA reminder, as on create. Replaces the one the draft has, and null removes it.
remind_conditionstringnoAs 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

GET/v1/mailboxes/{mailbox_uuid}/signatures

Returns 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#

FieldTypeRequiredDescription
objectstringnoAlways label.
uuidstringnoThe label.
namestringnoIts name.
typestringnoA system type such as inbox, or user for a custom label.
colorstring | nullnoIts color.
descriptionstring | nullnoIts description.
is_visiblebooleannoWhether the mail app shows it in the sidebar.
positionnumbernoSort position.

List labels

GET/v1/mailboxes/{mailbox_uuid}/labels

Returns the mailbox’s system and custom labels, in the order of the mail app’s sidebar. Not paginated. Scope email.read.

Create a label

POST/v1/mailboxes/{mailbox_uuid}/labels

Creates 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.

FieldTypeRequiredDescription
namestringyesThe name.

Rename or delete a label

POST/v1/mailboxes/{mailbox_uuid}/labels/{label_uuid}
DELETE/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.

FieldTypeRequiredDescription
objectstringnoAlways email_filter_rule.
uuidstringnoThe filter.
mailbox_uuidstringnoThe mailbox it runs in.
namestringnoIts name.
descriptionstring | nullnoIts description.
statusstringnoactive or inactive.
prioritynumbernoThe order it runs in, lowest first.
stop_processingbooleannoWhether later filters are skipped after it matches.
condition_astobjectnoWhat it matches, as a tree. See below.
actionsarraynoWhat it does. See below.
match_countnumbernoHow many emails it has matched.
last_matched_atstring | nullnoWhen it last matched.
created_atstringnoWhen it was created.
updated_atstring | nullnoWhen 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.

FieldTypeDescription
containsfield, valuefield is from, to, cc, bcc, subject, body, message_id or text.
equalsfield, valueThe same fields, without message_id and text.
dateafter datebeforefield, valuefield is received_at or created_at, value a date such as 2026-01-15.
flagfield, valuefield is seen, answered, flagged or deleted, value a boolean.
hasattachment isreply isnewsletter fromcontactvalueA boolean value.
sizegreaterthan sizelessthanbytesA whole number of bytes.
fromcontactgroupcontact_group_uuidFrom 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

GET/v1/mailboxes/{mailbox_uuid}/filters
GET/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

POST/v1/mailboxes/{mailbox_uuid}/filters

Creates a filter and returns it with 201. Scope email.write.

FieldTypeRequiredDescription
namestringyesIts name.
condition_astobjectyesWhat it matches.
actionsarraynoWhat it does. Defaults to none.
descriptionstringnoA description.
statusstringnoactive (the default) or inactive.
prioritynumbernoIts place in the order. Defaults to 0.
stop_processingbooleannoDefaults 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

POST/v1/mailboxes/{mailbox_uuid}/filters/{filter_uuid}
DELETE/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.

FieldTypeRequiredDescription
objectstringnoAlways mailbox_address.
uuidstringnoThe address.
mailbox_uuidstringnoThe mailbox it delivers to.
addressstringnoThe full address, such as sales@example.com.
local_partstringnoThe part before the @.
domainstringnoThe domain.
is_primarybooleannoThe address the mailbox sends from by default. It cannot be deactivated or deleted.
deactivated_atstring | nullnoSet while it is switched off: mail to it is no longer delivered.
auto_created_atstring | nullnoSet when it was added by itself, the first time mail for it came in through a catch-all.
created_atstringnoWhen it was added.

List addresses

GET/v1/mailboxes/{mailbox_uuid}/addresses

Returns every address of the mailbox. Scope email.read.

Add an address

POST/v1/mailboxes/{mailbox_uuid}/addresses

Adds 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.

FieldTypeRequiredDescription
addressstringyesThe full address, such as sales@example.com.

Deactivate or make an address primary

POST/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.

FieldTypeRequiredDescription
deactivatedbooleannotrue to switch it off, false to switch it back on.
is_primarybooleannoOnly true. Not together with deactivating.

Delete an address

DELETE/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:

StatuserrorWhen
400invalid_bodyA 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.
400invalid_formatThe format in /get/{format} is not body or raw.
402subscription_inactiveThe workspace needs an active subscription to send mail.
403forbiddenA workspace API key tried to change an address, or you may not manage this mailbox’s addresses.
404not_foundThe 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.
404signature_not_foundThe signature named in a draft is not in the mailbox, or the mailbox has no default one.
404attachment_not_foundA file in attachments or add_attachments names an email attachment you cannot read. drive_file_not_found is its Drive twin.
409address_takenThe address is already in use.
422invalid_valueA 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).
422invalid_stateThe 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.
422incoherent_label_combinationAdding this label would put the email in two locations. Archive, trash or move it instead.
422protected_labelSystem labels cannot be renamed or deleted.
422mailbox_mismatchThe email you reply to or forward is in another mailbox. mailbox_uuid in the body says which.
422not_a_draftThe uuid names an email that is not a draft.
422already_scheduledThe draft is scheduled to be sent, so it cannot be changed or sent now.
422too_largeAn attached file is over 25 MB, or together they are over 35 MB. Other refusals of a file: not_uploaded, infected, trashed.
422invalid_queryThe search query is missing or cannot be read. The description says what to fix.
429rate_limitedA send reached the workspace or mailbox sending limit. Wait for Retry-After seconds.
504search_timeoutThe search took too long. Narrow the query.