Provisioning API

List mailboxes for a sender

GET

/senders/{sender_id}/mailboxes

const url = 'https://live-api.customers.ac/v1/senders/snd_a1b2c3d4-e5f6-7890-abcd-ef1234567890/mailboxes?page%5Bsize%5D=25&filter%5Bstatus%5D=pending&include=credentials';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://live-api.customers.ac/v1/senders/snd_a1b2c3d4-e5f6-7890-abcd-ef1234567890/mailboxes?page%5Bsize%5D=25&filter%5Bstatus%5D=pending&include=credentials' \
  --header 'Authorization: Bearer <token>'

Returns all mailboxes belonging to a sender. By default, credentials are not included. Pass include=credentials to include IMAP and SMTP credentials in the response.

Security note: Only request credentials when you need them. Credential responses are logged separately for audit purposes.

Authorizations

BearerAuth
mailboxes:read

Parameters

Path Parameters

sender_id

required

string format: uuid

Example

snd_a1b2c3d4-e5f6-7890-abcd-ef1234567890

The unique identifier of the sender.

Query Parameters

page[size]

integer

default: 25 >= 1 <= 100

Maximum number of records to return. Default: 25, maximum: 100.

page[after]

string

Opaque cursor returned by a previous list response. Pass this to fetch the next page.

filter[status]

The current lifecycle status of a mailbox.

string

Allowed values: pending provisioning active suspended deprovisioned

Return only mailboxes with this status.

filter[domain_id]

string format: uuid

Return only mailboxes on this domain.

include

string

Allowed values: credentials

Comma-separated list of related resources to include. Supported values: credentials.

Responses

200

A paginated list of mailboxes.

application/json

object

data

required

Array<object>

object

required

Unique identifier for the mailbox.

string format: uuid

domain_id

required

The domain this mailbox belongs to.

string format: uuid

sender_id

required

The sender this mailbox belongs to (denormalized for convenience).

string format: uuid

email

required

The full email address of this mailbox.

string format: email

display_name

The display name configured on this mailbox.

string | null

status

required

The current lifecycle status of a mailbox.

string

Allowed values: pending provisioning active suspended deprovisioned

credentials

IMAP and SMTP credentials. Only included when ?include=credentials is passed. Omitted by default for security.

object

mailbox_id

required

string format: uuid

email

required

string format: email

imap

required

object

host

required

IMAP server hostname.

string

port

required

IMAP server port.

integer

username

required

IMAP login username (typically the email address).

string

password

required

IMAP login password.

string

encryption

required

Connection encryption method.

string

Allowed values: SSL/TLS STARTTLS none

smtp

required

object

host

required

SMTP server hostname.

string

port

required

SMTP server port.

integer

username

required

SMTP login username (typically the email address).

string

password

required

SMTP login password.

string

encryption

required

Connection encryption method.

string

Allowed values: SSL/TLS STARTTLS none

created_at

required

string format: date-time

updated_at

required

string format: date-time

pagination

required

Cursor-based pagination metadata.

object

has_more

required

true if there are more records after this page.

boolean

next_cursor

Pass this value as page[after] to fetch the next page. null when there are no more records.

string | null

Example

{
  "data": [
    {
      "id": "mbx_f6a7b8c9-d0e1-2345-f678-901234567890",
      "domain_id": "dom_d4e5f6a7-b8c9-0123-def4-567890123456",
      "sender_id": "snd_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "jane@outbound.acme.com",
      "display_name": "Jane Doe",
      "status": "pending",
      "credentials": {
        "mailbox_id": "mbx_f6a7b8c9-d0e1-2345-f678-901234567890",
        "email": "jane@outbound.acme.com",
        "imap": {
          "host": "outlook.office365.com",
          "port": 993,
          "username": "jane@outbound.acme.com",
          "password": "xK9#mP2$vL5nQ8wR",
          "encryption": "SSL/TLS"
        },
        "smtp": {
          "host": "smtp.office365.com",
          "port": 587,
          "username": "jane@outbound.acme.com",
          "password": "xK9#mP2$vL5nQ8wR",
          "encryption": "SSL/TLS"
        }
      },
      "created_at": "2026-03-21T14:30:00Z",
      "updated_at": "2026-03-21T14:35:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6InVzcl96OXk4eDd3NiJ9"
  }
}

401

Authentication failed. The API key is missing or invalid.

application/json

object

error

required

object

code

required

A machine-readable error code.

string

Allowed values: auth.missing_key auth.invalid_key auth.insufficient_scope rate.quota_exceeded validation.required_field validation.invalid_value resource.not_found resource.already_exists resource.not_ready server.error

message

required

A human-readable explanation of the error.

string

doc_url

A link to the documentation page for this error code.

string format: uri

details

For validation errors, a list of individual field-level problems.

Array<object> | null

object

field

required

The field that caused the error, in dot notation.

string

code

A machine-readable code for this specific validation issue.

string

message

required

A human-readable explanation.

string

Examples

No API key provided

{
  "error": {
    "code": "auth.missing_key",
    "message": "No API key was provided. Include your key in the Authorization header: Bearer sac_live_xxxxx.",
    "doc_url": "https://docs.sending.ac/errors/auth-missing-key"
  }
}

Invalid API key

{
  "error": {
    "code": "auth.invalid_key",
    "message": "The API key provided is invalid or has been revoked.",
    "doc_url": "https://docs.sending.ac/errors/auth-invalid-key"
  }
}

403

The API key does not have the required scope for this operation.

application/json

object

error

required

object

code

required

A machine-readable error code.

string

message

required

A human-readable explanation of the error.

string

doc_url

A link to the documentation page for this error code.

string format: uri

details

For validation errors, a list of individual field-level problems.

Array<object> | null

object

field

required

The field that caused the error, in dot notation.

string

code

A machine-readable code for this specific validation issue.

string

message

required

A human-readable explanation.

string

Example

{
  "error": {
    "code": "auth.insufficient_scope",
    "message": "Your API key does not have the 'senders:write' scope required for this operation.",
    "doc_url": "https://docs.sending.ac/errors/auth-insufficient-scope"
  }
}

404

The requested resource does not exist.

application/json

object

error

required

object

code

required

A machine-readable error code.

string

message

required

A human-readable explanation of the error.

string

doc_url

A link to the documentation page for this error code.

string format: uri

details

For validation errors, a list of individual field-level problems.

Array<object> | null

object

field

required

The field that caused the error, in dot notation.

string

code

A machine-readable code for this specific validation issue.

string

message

required

A human-readable explanation.

string

Example

{
  "error": {
    "code": "resource.not_found",
    "message": "No sender found with ID snd_a1b2c3d4-e5f6-7890-abcd-ef1234567890.",
    "doc_url": "https://docs.sending.ac/errors/resource-not-found"
  }
}

429

You have exceeded the rate limit. Wait and retry.

application/json

object

error

required

object

code

required

A machine-readable error code.

string

message

required

A human-readable explanation of the error.

string

doc_url

A link to the documentation page for this error code.

string format: uri

details

For validation errors, a list of individual field-level problems.

Array<object> | null

object

field

required

The field that caused the error, in dot notation.

string

code

A machine-readable code for this specific validation issue.

string

message

required

A human-readable explanation.

string

Example

{
  "error": {
    "code": "rate.quota_exceeded",
    "message": "Rate limit exceeded. You may make 120 requests per minute. Retry after 30 seconds.",
    "doc_url": "https://docs.sending.ac/errors/rate-quota-exceeded"
  }
}

Headers

Retry-After

integer

Example

Number of seconds to wait before retrying.

X-RateLimit-Limit

integer

Example

The maximum number of requests allowed per minute.

X-RateLimit-Remaining

integer

Example

The number of requests remaining in the current window.

X-RateLimit-Reset

integer

Example

1711267260

Unix timestamp when the rate limit window resets.