About the Email API
View as MarkdownHow the Email API is structured, how mailbox provisioning works, and how the core resources relate to each other.
Overview
The Email API provisions and manages email mailboxes for domains owned by the authenticated account. All paths are under /v1/email/, and every operation is scoped to domains the calling account already owns. There's no separate step to associate a domain first.
The API exposes a single core resource, Mailbox, plus an eligibility check that tells you whether a mailbox can be provisioned for a given address before you attempt to create one.
How mailbox creation works
Creating a mailbox is asynchronous. POST /v1/email/mailboxes returns 202 Accepted with the mailbox in its initial state (status: EXECUTING). Poll GET /v1/email/mailboxes/{mailboxId} until status reaches COMPLETED or FAILED.
Note
EXECUTING, COMPLETED, FAILED, and DELETED are the valid statuses for a mailbox. Go to Provision a mailbox for the full polling procedure.
The Mailbox object
The following table describes the fields of the Mailbox object:
| Field | Description | Note |
|---|---|---|
mailboxId | Unique identifier for the mailbox. | Returned from POST /v1/email/mailboxes, used as the path parameter on GET /v1/email/mailboxes/{mailboxId}. |
emailAddress | Mailbox email address. | |
mailboxType | Underlying email platform. | For example, TITAN. Auto-selected from the domain's entitlements at creation (you don't choose it). |
firstName / lastName | Mailbox owner's name. | |
displayName | Display name shown to recipients. | |
status | Provisioning status. | EXECUTING, COMPLETED, FAILED, or DELETED. |
createdAt / updatedAt | ISO 8601 timestamps. | |
links | Hypermedia links related to the mailbox, including self. |
Eligibility, entitlements, and consents
Before the platform can provision a mailbox, three conditions must align: the address must be eligible, the account must have an entitlement (a provisioning credit tied to the domain), and any requirements on that entitlement must be consented to.
Call GET /v1/email/check-mailbox-eligibility to evaluate all three before attempting POST /v1/email/mailboxes. The response is an EligibilityResult:
| Field | Description | Note |
|---|---|---|
isEligible | Whether a mailbox can be provisioned for the requested address. | When false, the API returns an error response with details. |
eligibleAccounts | Entitlements available to provision with. | Each entry has accountId, mailboxType, accountName, and a default flag. |
An entitlement might carry requirements (conditions the caller must accept before provisioning). A free-trial entitlement, for example, might require FREETRIAL_AUTORENEW consent. Pass any requirements as consents in the POST /v1/email/mailboxes request body. The created mailbox includes the accepted consents as agreements.
Go to Provision a mailbox for the full request and response shapes.
OAuth scopes
The following table lists the OAuth scopes required for managing email mailboxes. Request only the scopes your integration needs.
| Scope | What it grants |
|---|---|
email.mailbox:read | List email mailboxes for domains owned by the authenticated account. |
email.mailbox:create | Create email mailboxes for domains owned by the authenticated account. |
Go to Authentication for how to generate a PAT with these scopes.
Related
API References
Concepts
Last updated on
How is this guide?