September 29, 2026: The Email API is now available for provisioning new mailboxes

You can now provision and manage mailboxes on domains your account owns. The Email API covers eligibility checks, mailbox creation, and mailbox lookup.

What changed

Four endpoints are available under /v1/email:

• GET /v1/email/check-mailbox-eligibility — check whether an address can be provisioned and which entitlements are available.
• POST /v1/email/mailboxes — create a mailbox.
• GET /v1/email/mailboxes — list mailboxes across account-owned domains, filtered by status and paged with page and pageSize.
• GET /v1/email/mailboxes/{mailboxId} — read one mailbox.

Every endpoint authenticates with a Personal Access Token (PAT). The email.mailbox:read scope grants the read operations; email.mailbox:create grants mailbox creation.

Creation is asynchronous. POST /v1/email/mailboxes returns 202 Accepted with the mailbox at status: EXECUTING; poll GET /v1/email/mailboxes/{mailboxId} until status reaches COMPLETED or FAILED. The create request requires an Idempotency-Key header, so retrying with the same key returns the original response instead of creating a second mailbox. We select mailboxType from the domain's entitlements — you don't set it.

Some entitlements carry requirements — legal agreements you must accept before provisioning. The eligibility response lists them under requirements; pass matching consents in the create request body.

The same flow is available from the terminal. The gddy CLI adds a gddy email command family:

• gddy email check-eligibility --email <email> — check eligibility and list the accounts a mailbox can be created under.
• gddy email create --email <email> — provision a mailbox. Pass one --consent <type> per outstanding requirement. --account-id is optional when exactly one eligible account is marked default.
• gddy email get <mailbox-id> — read one mailbox, and poll provisioning status.
• gddy email list — list your mailboxes, with --status, --field, --page, --page-size, and --total-required.

gddy email create needs the email.mailbox:create scope; the other three need email.mailbox:read. Run gddy guide email for a walkthrough of the eligibility-to-creation flow.

Who is affected

Available to developers with a GoDaddy account, through the REST endpoints or the gddy CLI. Both need a credential carrying the email.mailbox scopes, and mailboxes can only be provisioned on domains the authenticated account already owns. No existing integrations are affected; these are new endpoints and new commands, and no action is required. Every other gddy command family is unchanged.

Links

• About the Email API — resources, mailbox statuses, eligibility, and scopes
• Provision a mailbox — guide, from eligibility check to polling
• List and look up mailboxes — guide, filtering and pagination
• Check eligibility reference, Create mailbox reference, List mailboxes reference, Get mailbox reference — endpoint schemas
• Set up the CLI — install and authenticate gddy
• Generate a PAT — create a token with the email.mailbox scopes
• Handle errors — error envelope and idempotency behavior

Last updated on