API reference

Mail

Read, organize and send mail from the mailboxes you belong to.

Read the Guide

GET/v1/orgs/:orgId/mail/mailboxes

The mailboxes the caller is a member of, with their aliases and signature. Keys get an empty list.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).

Query parameters

labelsstring
Up to 100 characters.

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  mailboxes: {
    mailboxId: string
    address: string
    domain: string
    displayName: string
    signature: string
    reminderMail: boolean
    aliases: string[]
  }[]
}
| {
  mailboxes: {
    mailboxId: string
    address: string
    domain: string
    displayName: string
    signature: string
    reminderMail: boolean
    aliases: string[]
  }[]
  labels: null | {
    mailboxId: string
    labels: {
      labelId: string
      name: string
    }[]
  }
}

GET/v1/orgs/:orgId/mail/preferences

The caller's Mail preferences in the organization: categories (the inbox's category bar on or off) and push per mailbox (all, primary or off; primary unless changed).

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).

Errors

403Mailboxes are only available to members.

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/preferences' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  preferences: {
    categories: boolean
    push: {
      [key: string]: "off" | "all" | "primary"
    }
  }
}

PATCH/v1/orgs/:orgId/mail/preferences

Changes the caller's Mail preferences: categories, and push for any of their mailboxes.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).

Request body

categoriesboolean
pushobject
Keys up to 100 characters. Values: "all" | "primary" | "off".

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/preferences' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "categories": true,
    "push": {}
  }'

Send it from this page with your session or a key.

Response 200

{
  preferences: {
    categories: boolean
    push: {
      [key: string]: "off" | "all" | "primary"
    }
  }
}

GET/v1/orgs/:orgId/mail/threads

All Mailboxes: one page of a view (inbox, starred, sent, drafts) across every mailbox the caller reads in the organization, newest first; each row names its mailboxId. In the inbox, category narrows it. With q, search results across those mailboxes (outside Spam and Trash, whatever the view), paged the same way. The cursor holds one position per mailbox, so pages merge without gaps or repeats; a page can be short while cursor is set.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).

Query parameters

view"inbox" | "starred" | "sent" | "drafts"
Default "inbox".
category"primary" | "transactions" | "updates" | "promotions"
qstring
Up to 200 characters.
cursorstring
Up to 20,000 characters.

Errors

403Mailboxes are only available to members.

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/threads' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  threads: {
    mailboxId: string
    orgId?: string
    threadId: string
    subject: string
    snippet: string
    participants: string[]
    lastAt: number
    messageCount: number
    unreadCount: number
    starred: boolean
    labels: string[]
    box: "archive" | "trash" | "inbox" | "spam"
    hasAttachments: boolean
    category: "primary" | "transactions" | "updates" | "promotions"
    sender?: string
    draftId?: string
    snoozedUntil?: number
    sendAt?: number
  }[]
  cursor: null | string
}

GET/v1/orgs/:orgId/mail/counts

Unread inbox conversations per category across the caller's mailboxes in the organization (counts) and for each (mailboxes), and badge: unread Primary conversations in the mailboxes they get push for, in every organization they belong to (what the Mail app shows on its icon).

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).

Errors

403Mailboxes are only available to members.

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/counts' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  counts: {
    primary: number
    transactions: number
    updates: number
    promotions: number
  }
  mailboxes: {
    [key: string]: {
      primary: number
      transactions: number
      updates: number
      promotions: number
    }
  }
  badge: number
  complete: boolean
}

PATCH/v1/orgs/:orgId/mail/mailboxes/:mailboxId/settings

Sets the mailbox's signature.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Request body

signaturestring
Up to 20,000 characters.
reminderMailboolean

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/settings' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "signature": "example",
    "reminderMail": true
  }'

Send it from this page with your session or a key.

Response 200

{
  mailbox: {
    mailboxId: string
    address: string
    domain: string
    displayName: string
    signature: string
    reminderMail: boolean
    aliases: string[]
  }
}

GET/v1/orgs/:orgId/mail/mailboxes/:mailboxId/limits

The organization's sending limits: messages per day, message size and recipients per message.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/limits' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  limits: {
    sendPerDay: number
    maxMessageMb: number
    maxRecipients: number
  }
}

GET/v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads

One page of conversations in a view (inbox, starred, sent, drafts, archive, all, spam, trash, or label with label), newest first, optionally matching q. In the inbox, category (primary, transactions, updates, promotions) narrows it to one category. Each row has its category and sender. Pass cursor to continue.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Query parameters

view"inbox" | "starred" | "snoozed" | "sent" | "drafts" | "scheduled" | "archive" | "all" | "spam" | "trash" | "label"
Default "inbox".
labelany JSON
qstring
Up to 200 characters.
category"primary" | "transactions" | "updates" | "promotions"
cursorstring
Up to 2,000 characters.

Errors

400Choose a label.
403Mailboxes are only available to members.
404Mailbox not found

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/threads' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  threads: {
    mailboxId: string
    orgId?: string
    threadId: string
    subject: string
    snippet: string
    participants: string[]
    lastAt: number
    messageCount: number
    unreadCount: number
    starred: boolean
    labels: string[]
    box: "archive" | "trash" | "inbox" | "spam"
    hasAttachments: boolean
    category: "primary" | "transactions" | "updates" | "promotions"
    sender?: string
    draftId?: string
    snoozedUntil?: number
    sendAt?: number
  }[]
  cursor: null | string
}

GET/v1/orgs/:orgId/mail/mailboxes/:mailboxId/counts

Unread conversations in the mailbox's inbox per category; complete is false when the inbox was too large to count whole.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/counts' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  counts: {
    primary: number
    transactions: number
    updates: number
    promotions: number
  }
  complete: boolean
}

PUT/v1/orgs/:orgId/mail/mailboxes/:mailboxId/senders/:address/category

Moves a sender's mail to a category: remembered for the mailbox's later mail from them, and applied now to threadId and the sender's other conversations in the inbox. Returns how many moved.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
address
An email address (URL-encoded): the alias, or the forwarding address; under marketing a person's email address or mobile number.

Request body

category"primary" | "transactions" | "updates" | "promotions"required
threadIdany JSON

Errors

400Enter a valid email address.
403Mailboxes are only available to members.
404Mailbox not found

curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/senders/{address}/category' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "category": "primary"
  }'

Send it from this page with your session or a key.

Response 200

{
  moved: number
}

POST/v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/actions

Applies one action to up to 100 conversations: archive, move to inbox, trash, spam, not spam, delete (from trash or spam only), read, unread, star, unstar, label or unlabel.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Request body

threadIdsany JSON[]required
1–100 items.
action"archive" | "inbox" | "trash" | "spam" | "not_spam" | "delete" | "read" | "unread" | "star" | "unstar" | "label" | "unlabel" | "snooze" | "unsnooze"required
labelIdany JSON
untilinteger

Errors

400Choose a label.
400Choose when the conversation comes back.
400Move the conversation to trash first.
403Mailboxes are only available to members.
404Mailbox not found
404Label not found

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/threads/actions' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "threadIds": [
      {}
    ],
    "action": "archive"
  }'

Send it from this page with your session or a key.

Response 200

{
  changed: number
}

GET/v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId

A conversation and its messages, without bodies.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
threadId
Conversation id (thr_…), or in Mirage a thread id (mth_…).

Query parameters

bodiesstring

Errors

403Mailboxes are only available to members.
404Mailbox not found
404Thread not found

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/threads/{threadId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  thread: {
    mailboxId: string
    orgId?: string
    threadId: string
    subject: string
    snippet: string
    participants: string[]
    lastAt: number
    messageCount: number
    unreadCount: number
    starred: boolean
    labels: string[]
    box: "archive" | "trash" | "inbox" | "spam"
    hasAttachments: boolean
    category: "primary" | "transactions" | "updates" | "promotions"
    sender?: string
    draftId?: string
    snoozedUntil?: number
    sendAt?: number
  }
  messages: {
    sendAt?: number
    messageId: string
    threadId: string
    kind: "in" | "sent" | "draft"
    from: {
      name?: string
      address: string
    }
    to: {
      name?: string
      address: string
    }[]
    cc: {
      name?: string
      address: string
    }[]
    bcc: {
      name?: string
      address: string
    }[]
    replyTo: {
      name?: string
      address: string
    }[]
    subject: string
    snippet: string
    at: number
    unread: boolean
    size: number
    rfcMessageId: string
    attachments: {
      index: number
      filename: string
      contentType: string
      size: number
      cid?: string
      inline: boolean
    }[]
    spam: boolean
    verdicts?: {
      [key: string]: string
    }
    deliveryStatus?: "failed" | "rejected" | "bounced" | "complained" | "sent" | "delivered" | "sending" | "delayed"
    deliveryDetail?: string
    meta: {
      unsubscribe?: {
        http?: string
        mailto?: string
        oneClick?: boolean
      }
      signedBy?: string[]
      mailedBy?: string
      arc?: string
      calendar?: string
      automated?: boolean
      origin?: {
        ip: string
        country: string
        region?: string
        city?: string
      }
    }
  }[]
}
| {
  bodies: {
    [key: string]: {
      text: string
      html?: string
      inline: {
        [key: string]: string
      }
    }
  }
  thread: {
    mailboxId: string
    orgId?: string
    threadId: string
    subject: string
    snippet: string
    participants: string[]
    lastAt: number
    messageCount: number
    unreadCount: number
    starred: boolean
    labels: string[]
    box: "archive" | "trash" | "inbox" | "spam"
    hasAttachments: boolean
    category: "primary" | "transactions" | "updates" | "promotions"
    sender?: string
    draftId?: string
    snoozedUntil?: number
    sendAt?: number
  }
  messages: {
    sendAt?: number
    messageId: string
    threadId: string
    kind: "in" | "sent" | "draft"
    from: {
      name?: string
      address: string
    }
    to: {
      name?: string
      address: string
    }[]
    cc: {
      name?: string
      address: string
    }[]
    bcc: {
      name?: string
      address: string
    }[]
    replyTo: {
      name?: string
      address: string
    }[]
    subject: string
    snippet: string
    at: number
    unread: boolean
    size: number
    rfcMessageId: string
    attachments: {
      index: number
      filename: string
      contentType: string
      size: number
      cid?: string
      inline: boolean
    }[]
    spam: boolean
    verdicts?: {
      [key: string]: string
    }
    deliveryStatus?: "failed" | "rejected" | "bounced" | "complained" | "sent" | "delivered" | "sending" | "delayed"
    deliveryDetail?: string
    meta: {
      unsubscribe?: {
        http?: string
        mailto?: string
        oneClick?: boolean
      }
      signedBy?: string[]
      mailedBy?: string
      arc?: string
      calendar?: string
      automated?: boolean
      origin?: {
        ip: string
        country: string
        region?: string
        city?: string
      }
    }
  }[]
}

GET/v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId/messages/:messageId/body

A message's text and HTML, with short-lived links for inline images. Reading a received message marks it read.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
threadId
Conversation id (thr_…), or in Mirage a thread id (mth_…).
messageId
Message id (msg_…; Mirage messages are mmg_…).

Errors

403Mailboxes are only available to members.
404Mailbox not found
404Message not found

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/threads/{threadId}/messages/{messageId}/body' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  text: string
  html?: string
  inline: {
    [key: string]: string
  }
}

GET/v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId/messages/:messageId/attachments/:index

A short-lived download link for an attachment.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
threadId
Conversation id (thr_…), or in Mirage a thread id (mth_…).
messageId
Message id (msg_…; Mirage messages are mmg_…).
index
The attachment's position in the message, from 0; or a Takeout archive's place in its import's files.

Errors

403Mailboxes are only available to members.
404Mailbox not found
404Message not found
404Attachment not found

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/threads/{threadId}/messages/{messageId}/attachments/{index}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  url: string
  filename: string
}

GET/v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId/messages/:messageId/raw

A short-lived link to the original message (.eml).

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
threadId
Conversation id (thr_…), or in Mirage a thread id (mth_…).
messageId
Message id (msg_…; Mirage messages are mmg_…).

Errors

403Mailboxes are only available to members.
404Mailbox not found
404Message not found
404No original for this message

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/threads/{threadId}/messages/{messageId}/raw' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  url: string
}

POST/v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId/messages/:messageId/unsubscribe

Leaves the mailing list a message came from: one-click (RFC 8058) when the sender offers it, else an unsubscribe email from this mailbox; otherwise the link for the reader to open.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:send

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
threadId
Conversation id (thr_…), or in Mirage a thread id (mth_…).
messageId
Message id (msg_…; Mirage messages are mmg_…).

Errors

403Mailboxes are only available to members.
404Mailbox not found
404Message not found
404This message has no unsubscribe link.
409This mailbox's domain was removed.
409… isn't verified for sending yet.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/threads/{threadId}/messages/{messageId}/unsubscribe' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  done: true
  method: string
}
| {
  done: false
  url: string
}

GET/v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId/messages/:messageId/invitation

The meeting a message carries and the event it became in this mailbox's calendars.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: calendar:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
threadId
Conversation id (thr_…), or in Mirage a thread id (mth_…).
messageId
Message id (msg_…; Mirage messages are mmg_…).

Errors

403Mailboxes are only available to members.
404Mailbox not found
404Message not found
404This message has no invitation.

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/threads/{threadId}/messages/{messageId}/invitation' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  invitation: {
    timeZone: string
    recurring: boolean
    recurrenceId: null | number
    organizer: null | {
      email: string
      name?: string
    }
    attendees: number
    from: null | {
      name?: string
      email: string
    }
    event: null | {
      calendarId: string
      eventId: string
      status: "cancelled" | "confirmed" | "tentative"
      myStatus: null | "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
      isOrganizer: boolean
      sequence: number
      start: number
      end: number
      allDay: boolean
    }
    startDate?: string
    endDate?: string
    method: string
    uid: string
    summary: string
    location: string
    start: number
    end: number
    allDay: boolean
  }
}

POST/v1/orgs/:orgId/mail/mailboxes/:mailboxId/uploads

Compose attachments go straight to the bucket; the link only accepts the declared size and type.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:send

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Request body

filenamestringrequired
1–255 characters. Trimmed.
contentTypestring
Default "application/octet-stream". Up to 255 characters. Matches ^[\w.+-]+\/[\w.+-]+$. Trimmed.
sizeintegerrequired
≥ 0.

Errors

403Mailboxes are only available to members.
404Mailbox not found
413Attachments can be at most … MB in total.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/uploads' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "filename": "Example",
    "size": 1
  }'

Send it from this page with your session or a key.

Response 201

{
  uploadId: string
  url: string
  headers: {
    "content-type": string
  }
}

POST/v1/orgs/:orgId/mail/mailboxes/:mailboxId/send

Sends a message from the mailbox and files it in Sent. The domain must be verified. With replyTo, it's threaded as a reply; with draftId, the draft is removed. The response lists recipients that bounced or complained before.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:send

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Request body (up to 6,144 KB)

toobject[]
Default []. Up to 500 items.
to[].namestring
Up to 200 characters. Trimmed.
to[].addressstringrequired
Trimmed. Lowercased.
ccobject[]
Default []. Up to 500 items.
cc[].namestring
Up to 200 characters. Trimmed.
cc[].addressstringrequired
Trimmed. Lowercased.
bccobject[]
Default []. Up to 500 items.
bcc[].namestring
Up to 200 characters. Trimmed.
bcc[].addressstringrequired
Trimmed. Lowercased.
subjectstring
Default "". Up to 998 characters.
htmlstring
Up to 2,000,000 characters.
textstring
Up to 2,000,000 characters.
attachments(object | object)[]
Default []. Up to 50 items.
replyToobject
replyTo.threadIdany JSONrequired
replyTo.messageIdany JSONrequired
draftIdany JSON
sendAtinteger
undoSecondsinteger
1–30.

Errors

400Add at least one recipient.
403Mailboxes are only available to members.
404Mailbox not found
409This mailbox's domain was removed.
409… isn't verified for sending yet.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/send' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "to": [
      {
        "address": "example"
      }
    ],
    "cc": [
      {
        "address": "example"
      }
    ],
    "bcc": [
      {
        "address": "example"
      }
    ]
  }'

Send it from this page with your session or a key.

Response 201

{
  suppressed: {
    address: string
    reason: "bounce" | "complaint"
  }[]
  messageId: string
  threadId: string
  duplicate: boolean
  box?: undefined
  category: "primary" | "transactions" | "updates" | "promotions"
} | {
  suppressed: {
    address: string
    reason: "bounce" | "complaint"
  }[]
  messageId: string
  threadId: string
  duplicate: boolean
  box: "archive" | "trash" | "inbox" | "spam"
  category?: "primary" | "transactions" | "updates" | "promotions"
}

Response 202

{
  draftId: string
  threadId: string
  sendAt: number
}

POST/v1/orgs/:orgId/mail/mailboxes/:mailboxId/recipients/check

Recipients that bounced or complained before, so compose can warn.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:send

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Request body

addressesstring[]required
Up to 500 items. Each up to 254 characters.

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/recipients/check' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "addresses": [
      "example"
    ]
  }'

Send it from this page with your session or a key.

Response 200

{
  suppressed: {
    address: string
    reason: "bounce" | "complaint"
  }[]
}

GET/v1/orgs/:orgId/mail/mailboxes/:mailboxId/recipients/suggest

Address suggestions for compose and guest fields: the organization's people (their own mailboxes, by name), then contacts, then recent correspondents.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Query parameters

qstring
Default "". Up to 200 characters.

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/recipients/suggest' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  suggestions: {
    name?: string
    address: string
    source: "recent" | "contact" | "directory"
  }[]
}

POST/v1/orgs/:orgId/mail/mailboxes/:mailboxId/drafts

Saves a new draft.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:send

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Request body (up to 6,144 KB)

toobject[]
Default []. Up to 500 items.
to[].namestring
Up to 200 characters. Trimmed.
to[].addressstringrequired
Trimmed. Lowercased.
ccobject[]
Default []. Up to 500 items.
cc[].namestring
Up to 200 characters. Trimmed.
cc[].addressstringrequired
Trimmed. Lowercased.
bccobject[]
Default []. Up to 500 items.
bcc[].namestring
Up to 200 characters. Trimmed.
bcc[].addressstringrequired
Trimmed. Lowercased.
subjectstring
Default "". Up to 998 characters.
htmlstring
Up to 2,000,000 characters.
textstring
Up to 2,000,000 characters.
attachments(object | object)[]
Default []. Up to 50 items.
replyToobject
replyTo.threadIdany JSONrequired
replyTo.messageIdany JSONrequired

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/drafts' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "to": [
      {
        "address": "example"
      }
    ],
    "cc": [
      {
        "address": "example"
      }
    ],
    "bcc": [
      {
        "address": "example"
      }
    ]
  }'

Send it from this page with your session or a key.

Response 201

{
  draftId: string
  threadId: string
}

GET/v1/orgs/:orgId/mail/mailboxes/:mailboxId/drafts/:draftId

A draft, for editing.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:send

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
draftId
Draft id: the draft's message id (msg_…).

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/drafts/{draftId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  draft: {
    failed?: string
    sendAt?: number
    draftId: string
    threadId: string
    replyTo?: {
      threadId: string
      messageId: string
    }
    to: {
      name?: string
      address: string
    }[]
    cc: {
      name?: string
      address: string
    }[]
    bcc: {
      name?: string
      address: string
    }[]
    subject?: string
    html?: string
    text: string
    attachments: {
      uploadId: string
      filename: string
      contentType: string
      size: number
      cid?: string
      inline?: boolean
    } | {
      threadId: string
      messageId: string
      index: number
      filename: string
      contentType: string
      size: number
      cid?: string
      inline?: boolean
    }[]
  }
}

PUT/v1/orgs/:orgId/mail/mailboxes/:mailboxId/drafts/:draftId

Replaces a draft.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:send

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
draftId
Draft id: the draft's message id (msg_…).

Request body (up to 6,144 KB)

toobject[]
Default []. Up to 500 items.
to[].namestring
Up to 200 characters. Trimmed.
to[].addressstringrequired
Trimmed. Lowercased.
ccobject[]
Default []. Up to 500 items.
cc[].namestring
Up to 200 characters. Trimmed.
cc[].addressstringrequired
Trimmed. Lowercased.
bccobject[]
Default []. Up to 500 items.
bcc[].namestring
Up to 200 characters. Trimmed.
bcc[].addressstringrequired
Trimmed. Lowercased.
subjectstring
Default "". Up to 998 characters.
htmlstring
Up to 2,000,000 characters.
textstring
Up to 2,000,000 characters.
attachments(object | object)[]
Default []. Up to 50 items.
replyToobject
replyTo.threadIdany JSONrequired
replyTo.messageIdany JSONrequired

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/drafts/{draftId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "to": [
      {
        "address": "example"
      }
    ],
    "cc": [
      {
        "address": "example"
      }
    ],
    "bcc": [
      {
        "address": "example"
      }
    ]
  }'

Send it from this page with your session or a key.

Response 200

{
  draftId: string
  threadId: string
}

DELETE/v1/orgs/:orgId/mail/mailboxes/:mailboxId/drafts/:draftId/schedule

Takes a scheduled draft off the schedule (it stays a draft).

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:send

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
draftId
Draft id: the draft's message id (msg_…).

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/drafts/{draftId}/schedule' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 204 with no body

DELETE/v1/orgs/:orgId/mail/mailboxes/:mailboxId/drafts/:draftId

Discards a draft.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:send

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
draftId
Draft id: the draft's message id (msg_…).

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/drafts/{draftId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 204 with no body

GET/v1/orgs/:orgId/mail/mailboxes/:mailboxId/filters

Inbound filters: conditions on received mail, actions on its conversation.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/filters' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  filters: {
    filterId: string
    match: {
      from?: string
      to?: string
      subject?: string
      words?: string
      hasAttachment?: boolean
    }
    actions: {
      labelId?: string
      archive?: boolean
      read?: boolean
      star?: boolean
      trash?: boolean
      forward?: string
    }
    enabled: boolean
  }[]
}

POST/v1/orgs/:orgId/mail/mailboxes/:mailboxId/filters

Creates an inbound filter: conditions on received mail (all must match), actions on its conversation. At most 100 per mailbox.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Request body

matchobjectrequired
match.fromstring
Up to 200 characters. Trimmed.
match.tostring
Up to 200 characters. Trimmed.
match.subjectstring
Up to 200 characters. Trimmed.
match.wordsstring
Up to 200 characters. Trimmed.
match.hasAttachmentboolean
actionsobjectrequired
actions.labelIdany JSON
actions.archiveboolean
actions.readboolean
actions.starboolean
actions.trashboolean
actions.forwardstring
Up to 254 characters. Trimmed. Lowercased.
enabledboolean

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/filters' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "match": {
      "from": "example",
      "to": "example",
      "subject": "Example"
    },
    "actions": {
      "labelId": {},
      "archive": true,
      "read": true
    }
  }'

Send it from this page with your session or a key.

Response 201

{
  filter: {
    filterId: string
    match: {
      from?: string
      to?: string
      subject?: string
      words?: string
      hasAttachment?: boolean
    }
    actions: {
      labelId?: string
      archive?: boolean
      read?: boolean
      star?: boolean
      trash?: boolean
      forward?: string
    }
    enabled: boolean
  }
}

PUT/v1/orgs/:orgId/mail/mailboxes/:mailboxId/filters/:filterId

Replaces a filter's conditions and actions, or turns it on or off.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
filterId
Filter id: a mail filter (flt_…) or a saved issue filter (ifl_…).

Request body

matchobjectrequired
match.fromstring
Up to 200 characters. Trimmed.
match.tostring
Up to 200 characters. Trimmed.
match.subjectstring
Up to 200 characters. Trimmed.
match.wordsstring
Up to 200 characters. Trimmed.
match.hasAttachmentboolean
actionsobjectrequired
actions.labelIdany JSON
actions.archiveboolean
actions.readboolean
actions.starboolean
actions.trashboolean
actions.forwardstring
Up to 254 characters. Trimmed. Lowercased.
enabledboolean

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/filters/{filterId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "match": {
      "from": "example",
      "to": "example",
      "subject": "Example"
    },
    "actions": {
      "labelId": {},
      "archive": true,
      "read": true
    }
  }'

Send it from this page with your session or a key.

Response 200

{
  filter: {
    filterId: string
    match: {
      from?: string
      to?: string
      subject?: string
      words?: string
      hasAttachment?: boolean
    }
    actions: {
      labelId?: string
      archive?: boolean
      read?: boolean
      star?: boolean
      trash?: boolean
      forward?: string
    }
    enabled: boolean
  }
}

POST/v1/orgs/:orgId/mail/mailboxes/:mailboxId/filters/:filterId/apply

Runs a filter over conversations already in the mailbox (a few seconds here, the rest in the background).

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
filterId
Filter id: a mail filter (flt_…) or a saved issue filter (ifl_…).

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/filters/{filterId}/apply' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  conversations: number
  scanned: number
  background: boolean
}

GET/v1/orgs/:orgId/mail/mailboxes/:mailboxId/forwarding

Forwarding addresses (filter action): added pending, confirmed with the code mailed to them.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/forwarding' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  addresses: {
    address: string
    status: "pending" | "verified"
    verifiedAt?: number
  }[]
}

POST/v1/orgs/:orgId/mail/mailboxes/:mailboxId/forwarding

Adds a forwarding address (or sends a new code to a pending one): the address gets a 6-digit code by email, valid 24 hours. Needs the mailbox's domain to be active; counts toward the daily sending limit.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:send

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Request body

addressstringrequired
Up to 254 characters. Trimmed. Lowercased.

Errors

403Mailboxes are only available to members.
404Mailbox not found
409This mailbox's domain was removed.
409… isn't verified for sending yet.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/forwarding' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "address": "example"
  }'

Send it from this page with your session or a key.

Response 201

{
  address: {
    address: string
    status: "pending"
  }
}

POST/v1/orgs/:orgId/mail/mailboxes/:mailboxId/forwarding/verify

Confirms a forwarding address with the code it received; filters can then forward to it. Five wrong codes need a new one.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:send

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Request body

addressstringrequired
Up to 254 characters. Trimmed. Lowercased.
codestringrequired
4–12 characters. Trimmed.

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/forwarding/verify' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "address": "example",
    "code": "example"
  }'

Send it from this page with your session or a key.

Response 200

{
  address: {
    address: string
    status: "pending" | "verified"
    verifiedAt?: number
  }
}

DELETE/v1/orgs/:orgId/mail/mailboxes/:mailboxId/forwarding/:address

Removes a forwarding address; filters forwarding to it stop forwarding.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:send

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
address
An email address (URL-encoded): the alias, or the forwarding address; under marketing a person's email address or mobile number.

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/forwarding/{address}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 204 with no body

DELETE/v1/orgs/:orgId/mail/mailboxes/:mailboxId/filters/:filterId

Deletes a filter. Mail already filed stays where it is.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
filterId
Filter id: a mail filter (flt_…) or a saved issue filter (ifl_…).

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/filters/{filterId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 204 with no body

GET/v1/orgs/:orgId/mail/mailboxes/:mailboxId/labels

The mailbox's labels, by name.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/labels' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  labels: {
    labelId: string
    name: string
  }[]
}

POST/v1/orgs/:orgId/mail/mailboxes/:mailboxId/labels

Creates a label. Names are unique in the mailbox, ignoring case.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Request body

namestringrequired
1–60 characters. Trimmed.

Errors

400A mailbox can have at most 200 labels.
403Mailboxes are only available to members.
404Mailbox not found
409A label with this name exists.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/labels' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example"
  }'

Send it from this page with your session or a key.

Response 201

{
  label: {
    labelId: string
    name: string
  }
}

DELETE/v1/orgs/:orgId/mail/mailboxes/:mailboxId/labels/:labelId

Deletes a label. Conversations stop showing it.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
labelId
Label id (lbl_…).

Errors

403Mailboxes are only available to members.
404Mailbox not found

curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/labels/{labelId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 204 with no body

GET/v1/me/mail/mailboxes

The caller's mailboxes in every organization where they read mail, each with its orgId and aliases, and those organizations (orgs: orgId, slug, name).

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Errors

403Mailboxes are only available to members.

curl 'https://api.cactive.com.au/v1/me/mail/mailboxes' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  mailboxes: {
    orgId: string
    mailboxId: string
    address: string
    domain: string
    displayName: string
    signature: string
    reminderMail: boolean
    aliases: string[]
  }[]
  orgs: {
    orgId: string
    slug: string
    name: string
  }[]
}

GET/v1/me/mail/threads

All Inboxes across organizations: one page of a view (inbox, starred, sent, drafts) across every mailbox the caller reads in every organization, newest first; each row names its mailboxId and orgId, and actions on it go to that organization's mailbox routes. In the inbox, category narrows it; with q, search results across them (outside Spam and Trash). Access is checked on every page: a mailbox the caller loses stops appearing, and one they gain starts below the rows already returned. The cursor holds one position per mailbox and the last row returned.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Query parameters

view"inbox" | "starred" | "sent" | "drafts"
Default "inbox".
category"primary" | "transactions" | "updates" | "promotions"
qstring
Up to 200 characters.
cursorstring
Up to 40,000 characters.

Errors

403Mailboxes are only available to members.

curl 'https://api.cactive.com.au/v1/me/mail/threads' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  threads: {
    mailboxId: string
    orgId?: string
    threadId: string
    subject: string
    snippet: string
    participants: string[]
    lastAt: number
    messageCount: number
    unreadCount: number
    starred: boolean
    labels: string[]
    box: "archive" | "trash" | "inbox" | "spam"
    hasAttachments: boolean
    category: "primary" | "transactions" | "updates" | "promotions"
    sender?: string
    draftId?: string
    snoozedUntil?: number
    sendAt?: number
  }[]
  cursor: null | string
}

GET/v1/me/mail/counts

Unread inbox conversations per category across the caller's mailboxes in every organization (counts) and for each (mailboxes), and badge: unread Primary conversations in the mailboxes they get push for.

Auth: A person's token or an API key, as Authorization: Bearer.

Get an API key

Errors

403Mailboxes are only available to members.

curl 'https://api.cactive.com.au/v1/me/mail/counts' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  counts: {
    primary: number
    transactions: number
    updates: number
    promotions: number
  }
  mailboxes: {
    [key: string]: {
      primary: number
      transactions: number
      updates: number
      promotions: number
    }
  }
  badge: number
  complete: boolean
}