Docs
Developer Portal

API reference

Mail administration

Mail domains, mailboxes, aliases, catch-all addresses and usage.
Read the Guide
GET/v1/orgs/:orgId/mail/domains

The organization's mail domains with their status, DNS records and which records were found.

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

Path parameters

  • orgId

    Organization id (org_…).

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/domains' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  domains: {
    domain: string
    status: "error" | "active" | "pending" | "verifying"
    region: string
    zone?: string
    dnsProvider?: string
    message?: string
    dkimMode: "easy" | "byo"
    dkimRotatedAt?: number
    records: {
      key: string
      purpose: "discovery" | "dkim" | "receiving" | "spf" | "dmarc" | "mailfrom"
      type: "CNAME" | "TXT" | "MX" | "SRV"
      name: string
      fqdn: string
      value: string
      priority?: number
      optional?: boolean
    }[]
    checks: {
      [key: string]: boolean
    }
    checkedAt?: number
    catchAllMailboxId?: string
    lent: boolean
    createdAt?: number
  }[]
}
POST/v1/orgs/:orgId/mail/domains

Adds a domain for sending and receiving mail: creates its sending identity and returns the DNS records to add. Hostnames under the platform's domain can't be added.

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

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • domainstringrequired

    Matches ^(?=.{4,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$. Trimmed. Lowercased.

Errors

  • 400Platform domains can't be added.
  • 409This domain is already in use.
  • 502Couldn't set up this domain. Try again.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/domains' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "example"
  }'
Send it from this page with your session or a key.

Response 201

{
  domain: {
    domain: string
    status: "error" | "active" | "pending" | "verifying"
    region: string
    zone?: string
    dnsProvider?: string
    message?: string
    dkimMode: "easy" | "byo"
    dkimRotatedAt?: number
    records: {
      key: string
      purpose: "discovery" | "dkim" | "receiving" | "spf" | "dmarc" | "mailfrom"
      type: "CNAME" | "TXT" | "MX" | "SRV"
      name: string
      fqdn: string
      value: string
      priority?: number
      optional?: boolean
    }[]
    checks: {
      [key: string]: boolean
    }
    checkedAt?: number
    catchAllMailboxId?: string
    lent: boolean
    createdAt?: number
  }
}
POST/v1/orgs/:orgId/mail/domains/:domain/dkim/rotate

A new DKIM key for the domain's mail (platform-generated keys only; the customer's DNS stays).

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

Path parameters

  • orgId

    Organization id (org_…).

  • domain

    The mail domain, e.g. example.com.

Errors

  • 404Domain not found
  • 502Couldn't rotate the key. The current key is still in use; try again.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/domains/{domain}/dkim/rotate' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  domain: {
    domain: string
    status: "error" | "active" | "pending" | "verifying"
    region: string
    zone?: string
    dnsProvider?: string
    message?: string
    dkimMode: "easy" | "byo"
    dkimRotatedAt?: number
    records: {
      key: string
      purpose: "discovery" | "dkim" | "receiving" | "spf" | "dmarc" | "mailfrom"
      type: "CNAME" | "TXT" | "MX" | "SRV"
      name: string
      fqdn: string
      value: string
      priority?: number
      optional?: boolean
    }[]
    checks: {
      [key: string]: boolean
    }
    checkedAt?: number
    catchAllMailboxId?: string
    lent: boolean
    createdAt?: number
  }
}
POST/v1/orgs/:orgId/mail/domains/:domain/verify

Checks the domain's DNS records and verification now.

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

Path parameters

  • orgId

    Organization id (org_…).

  • domain

    The mail domain, e.g. example.com.

Errors

  • 404Domain not found
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/domains/{domain}/verify' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  domain: {
    domain: string
    status: "error" | "active" | "pending" | "verifying"
    region: string
    zone?: string
    dnsProvider?: string
    message?: string
    dkimMode: "easy" | "byo"
    dkimRotatedAt?: number
    records: {
      key: string
      purpose: "discovery" | "dkim" | "receiving" | "spf" | "dmarc" | "mailfrom"
      type: "CNAME" | "TXT" | "MX" | "SRV"
      name: string
      fqdn: string
      value: string
      priority?: number
      optional?: boolean
    }[]
    checks: {
      [key: string]: boolean
    }
    checkedAt?: number
    catchAllMailboxId?: string
    lent: boolean
    createdAt?: number
  }
}
PATCH/v1/orgs/:orgId/mail/domains/:domain

Sets or clears the domain's catch-all mailbox, which receives mail to unknown addresses.

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

Path parameters

  • orgId

    Organization id (org_…).

  • domain

    The mail domain, e.g. example.com.

Request body

  • catchAllMailboxIdstringrequiredor null

    Up to 40 characters.

Errors

  • 404Domain not found
  • 404Mailbox not found
curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/domains/{domain}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "catchAllMailboxId": "<catchAllMailboxId>"
  }'
Send it from this page with your session or a key.

Response 200

{
  domain: {
    domain: string
    status: "error" | "active" | "pending" | "verifying"
    region: string
    zone?: string
    dnsProvider?: string
    message?: string
    dkimMode: "easy" | "byo"
    dkimRotatedAt?: number
    records: {
      key: string
      purpose: "discovery" | "dkim" | "receiving" | "spf" | "dmarc" | "mailfrom"
      type: "CNAME" | "TXT" | "MX" | "SRV"
      name: string
      fqdn: string
      value: string
      priority?: number
      optional?: boolean
    }[]
    checks: {
      [key: string]: boolean
    }
    checkedAt?: number
    catchAllMailboxId?: string
    lent: boolean
    createdAt?: number
  }
}
DELETE/v1/orgs/:orgId/mail/domains/:domain

Removes a domain and its aliases. Its mailboxes must be deleted first.

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

Path parameters

  • orgId

    Organization id (org_…).

  • domain

    The mail domain, e.g. example.com.

Errors

  • 404Domain not found
  • 409Delete this domain's mailboxes first.
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/domains/{domain}' \
  -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/members

Members of the organization, to choose mailbox members from.

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

Path parameters

  • orgId

    Organization id (org_…).

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/members' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  members: {
    userId: string
    email: string
    name?: string
  }[]
}
GET/v1/orgs/:orgId/mail/admin/mailboxes

Every mailbox of the organization with its members and aliases.

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

Path parameters

  • orgId

    Organization id (org_…).

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/admin/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
    members: string[]
    aliases: string[]
    createdAt?: number
  }[]
}
POST/v1/orgs/:orgId/mail/admin/mailboxes

Creates a mailbox at one of the organization's domains, with a sender name and members.

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

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • localPartstringrequired

    Matches ^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$. Trimmed. Lowercased.

  • domainstringrequired

    Trimmed. Lowercased.

  • displayNamestring

    Default "". Up to 200 characters. Trimmed.

  • membersstring[]

    Default []. Up to 100 items. Each up to 64 characters.

Errors

  • 400Mailbox members must belong to the organization.
  • 400Enter a valid address.
  • 404Domain not found
  • 409… is already in use.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/admin/mailboxes' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "localPart": "example",
    "domain": "example"
  }'
Send it from this page with your session or a key.

Response 201

{
  mailbox: {
    mailboxId: string
    address: string
    domain: string
    displayName: string
    members: string[]
    aliases: string[]
    createdAt?: number
  }
}
PATCH/v1/orgs/:orgId/mail/admin/mailboxes/:mailboxId

Changes a mailbox's sender name or members.

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

Path parameters

  • orgId

    Organization id (org_…).

  • mailboxId

    Mailbox id (mbx_…).

Request body

  • displayNamestring

    Up to 200 characters. Trimmed.

  • membersstring[]

    Up to 100 items. Each up to 64 characters.

Errors

  • 400Mailbox members must belong to the organization.
  • 404Mailbox not found
curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/admin/mailboxes/{mailboxId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "displayName": "Example",
    "members": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  mailbox: {
    mailboxId: string
    address: string
    domain: string
    displayName: string
    members: string[]
    aliases: string[]
    createdAt?: number
  }
}
DELETE/v1/orgs/:orgId/mail/admin/mailboxes/:mailboxId

Deletes a mailbox with all of its mail, drafts, labels and aliases.

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

Path parameters

  • orgId

    Organization id (org_…).

  • mailboxId

    Mailbox id (mbx_…).

Errors

  • 404Mailbox not found
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/admin/mailboxes/{mailboxId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 202

{
  background: true
}

Response 204 with no body

POST/v1/orgs/:orgId/mail/admin/mailboxes/:mailboxId/aliases

Adds another address, at one of the organization's domains, that delivers to the mailbox.

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

Path parameters

  • orgId

    Organization id (org_…).

  • mailboxId

    Mailbox id (mbx_…).

Request body

  • addressstringrequired

    Trimmed. Lowercased.

Errors

  • 400Enter a valid address.
  • 404Mailbox not found
  • 404Domain not found
  • 409… is already in use.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/admin/mailboxes/{mailboxId}/aliases' \
  -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

{
  mailbox: {
    mailboxId: string
    address: string
    domain: string
    displayName: string
    members: string[]
    aliases: string[]
    createdAt?: number
  }
}
DELETE/v1/orgs/:orgId/mail/admin/aliases/:address

Removes an alias.

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

Path parameters

  • orgId

    Organization id (org_…).

  • address

    An email address (URL-encoded): the alias, or the forwarding address; under marketing a person's email address or mobile number.

Errors

  • 404Alias not found
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/admin/aliases/{address}' \
  -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/usage

Messages sent, received, bounced and complained about per day, and the organization's sending limits.

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

Path parameters

  • orgId

    Organization id (org_…).

Query parameters

  • daysinteger

    Default 30. 1–90. Coerced from a string.

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/usage' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  days: {
    day: string
    sent: number
    received: number
    bounced: number
    complained: number
  }[]
  limits: {
    sendPerDay: number
    maxMessageMb: number
    maxRecipients: number
  }
}