API reference

Mail administration

Mail domains, mailboxes, aliases, catch-all addresses and usage.

Every route here needs mail:admin, which owners and admins have. See Mail.

`GET /v1/orgs/:orgId/mail/domains`

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

Auth: user access token or platform agent key · Scope: mail:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Response 200

{
  domains: {
    domain: string
    status: "error" | "active" | "pending" | "verifying"
    region: string
    zone?: string
    dnsProvider?: string
    message?: string
    dkimMode: "easy" | "byo"
    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
    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: user access token or platform agent key · Scope: mail:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Request body

Field	Type	Required	Notes
`domain`	`string`	Yes	matches `^(?=.{4,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$`; trimmed; lowercased

Response 201

{
  domain: {
    domain: string
    status: "error" | "active" | "pending" | "verifying"
    region: string
    zone?: string
    dnsProvider?: string
    message?: string
    dkimMode: "easy" | "byo"
    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
    createdAt?: number
  }
}

Errors

Status	Message
`400`	Platform domains can't be added.
`409`	Mail is not available in … yet.
`409`	This domain is already in use.
`502`	Couldn't set up this domain. Try again.

`POST /v1/orgs/:orgId/mail/domains/:domain/verify`

Checks the domain's DNS records and verification now.

Auth: user access token or platform agent key · Scope: mail:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:domain`	The mail domain, e.g. `example.com`.

Response 200

{
  domain: {
    domain: string
    status: "error" | "active" | "pending" | "verifying"
    region: string
    zone?: string
    dnsProvider?: string
    message?: string
    dkimMode: "easy" | "byo"
    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
    createdAt?: number
  }
}

Errors

Status	Message
`404`	Domain not found

`PATCH /v1/orgs/:orgId/mail/domains/:domain`

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

Auth: user access token or platform agent key · Scope: mail:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:domain`	The mail domain, e.g. `example.com`.

Request body

Field	Type	Required	Notes
`catchAllMailboxId`	`string`	Yes	up to 40 characters; can be `null`

Response 200

{
  domain: {
    domain: string
    status: "error" | "active" | "pending" | "verifying"
    region: string
    zone?: string
    dnsProvider?: string
    message?: string
    dkimMode: "easy" | "byo"
    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
    createdAt?: number
  }
}

Errors

Status	Message
`404`	Domain not found
`404`	Mailbox not found

`DELETE /v1/orgs/:orgId/mail/domains/:domain`

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

Auth: user access token or platform agent key · Scope: mail:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:domain`	The mail domain, e.g. `example.com`.

Response 204 with no body.

Errors

Status	Message
`404`	Domain not found
`409`	Delete this domain's mailboxes first.

`GET /v1/orgs/:orgId/mail/members`

Members of the organization, to choose mailbox members from.

Auth: user access token or platform agent key · Scope: mail:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).

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: user access token or platform agent key · Scope: mail:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).

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: user access token or platform agent key · Scope: mail:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Request body

Field	Type	Required	Default	Notes
`localPart`	`string`	Yes		matches `^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$`; trimmed; lowercased
`domain`	`string`	Yes		trimmed; lowercased
`displayName`	`string`	No	`""`	up to 200 characters; trimmed
`members`	`string[]`	No	`[]`	up to 100 items; each up to 64 characters

Response 201

{
  mailbox: {
    mailboxId: string
    address: string
    domain: string
    displayName: string
    members: string[]
    aliases: string[]
    createdAt?: number
  }
}

Errors

Status	Message
`400`	Mailbox members must belong to the organization.
`400`	Enter a valid address.
`404`	Domain not found
`409`	… is already in use.

`PATCH /v1/orgs/:orgId/mail/admin/mailboxes/:mailboxId`

Changes a mailbox's sender name or members.

Auth: user access token or platform agent key · Scope: mail:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).

Request body

Field	Type	Required	Notes
`displayName`	`string`	No	up to 200 characters; trimmed
`members`	`string[]`	No	up to 100 items; each up to 64 characters

Response 200

{
  mailbox: {
    mailboxId: string
    address: string
    domain: string
    displayName: string
    members: string[]
    aliases: string[]
    createdAt?: number
  }
}

Errors

Status	Message
`400`	Mailbox members must belong to the organization.
`404`	Mailbox not found

`DELETE /v1/orgs/:orgId/mail/admin/mailboxes/:mailboxId`

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

Auth: user access token or platform agent key · Scope: mail:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).

Response 204 with no body.

Errors

Status	Message
`404`	Mailbox not found

`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: user access token or platform agent key · Scope: mail:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).

Request body

Field	Type	Required	Notes
`address`	`string`	Yes	trimmed; lowercased

Response 201

{
  mailbox: {
    mailboxId: string
    address: string
    domain: string
    displayName: string
    members: string[]
    aliases: string[]
    createdAt?: number
  }
}

Errors

Status	Message
`400`	Enter a valid address.
`404`	Mailbox not found
`404`	Domain not found
`409`	… is already in use.

`DELETE /v1/orgs/:orgId/mail/admin/aliases/:address`

Removes an alias.

Auth: user access token or platform agent key · Scope: mail:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:address`	The alias address, e.g. `sales@example.com`.

Response 204 with no body.

Errors

Status	Message
`404`	Alias not found

`GET /v1/orgs/:orgId/mail/usage`

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

Auth: user access token or platform agent key · Scope: mail:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Query parameter	Type	Required	Default	Notes
`days`	`integer`	No	`30`	1–90; coerced from a string

Response 200

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

Mail administration

On this page