Provisioning API

Retrieve a mailbox

GET

/mailboxes/{mailbox_id}

const url = 'https://live-api.customers.ac/v1/mailboxes/mbx_f6a7b8c9-d0e1-2345-f678-901234567890';
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/mailboxes/mbx_f6a7b8c9-d0e1-2345-f678-901234567890 \
  --header 'Authorization: Bearer <token>'

Returns a single mailbox by ID. Credentials are not included — use the dedicated credentials endpoint.

Authorizations

BearerAuth
mailboxes:read

Parameters

Path Parameters

mailbox_id

required

string format: uuid

Example

mbx_f6a7b8c9-d0e1-2345-f678-901234567890

The unique identifier of the mailbox.

Responses

200

The requested mailbox.

application/json

object

data

required

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

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"
  }
}

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.