Provisioning API

Retrieve mailbox credentials

GET

/mailboxes/{mailbox_id}/credentials

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

Returns the IMAP and SMTP credentials for a single mailbox. This endpoint is logged separately for audit purposes.

Credentials are only available when the mailbox status is active.

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 mailbox credentials.

application/json

object

data

required

IMAP and SMTP connection details for a mailbox.

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

Example

{
  "data": {
    "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": "STARTTLS"
    }
  }
}

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

422

Credentials not yet available. The mailbox must be in active status.

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_ready",
    "message": "Credentials are not available until the mailbox is active. Current status: provisioning.",
    "doc_url": "https://docs.sending.ac/errors/resource-not-ready"
  }
}

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.