GoDaddy
Support
API ReferenceEmailEmail APICreate a new email mailbox POST

Create a new email mailbox

View as Markdown

Provisions a new email mailbox for a domain owned by the authenticated account.

Full description

| Provisions a new email mailbox for a domain owned by the authenticated account. Returns 202 Accepted with the mailbox in its initial state (status: EXECUTING). Poll GET /mailboxes/{mailboxId} until status reaches COMPLETED or FAILED.

POST
/mailboxes

Authorization

bearerAuth
AuthorizationBearer <token>

Personal Access Token (PAT). Generate one from the developer dashboard. Pass as: Authorization: Bearer <token>.

In: header

Header Parameters

X-Request-Id?string

Optional client-generated request correlation identifier. Propagated across services and echoed in the X-Request-Id response header.

Formatuuid
Idempotency-Key*string

Client-generated unique key (UUID recommended). Retrying a POST request with the same Idempotency-Key returns the original response without creating a duplicate mailbox.

Length16 <= length <= 64

Request Body

application/json

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/mailboxes" \  -H "Idempotency-Key: 9f1c2e7a-4b3d-4e8f-a1c2-3d4e5f6a7b8c" \  -H "Content-Type: application/json" \  -d '{    "emailAddress": "jane.smith@example.com",    "accountId": "00000000-0000-0000-0000-000000000001",    "firstName": "Jane",    "lastName": "Smith",    "consents": [      {        "type": "FREETRIAL_AUTORENEW"      }    ]  }'
{  "mailboxId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "emailAddress": "jane.smith@example.com",  "mailboxType": "TITAN",  "firstName": "Jane",  "lastName": "Smith",  "displayName": "Jane Smith",  "status": "EXECUTING",  "agreements": [    {      "type": "FREETRIAL_AUTORENEW",      "agreed": true    }  ],  "createdAt": "2024-06-15T12:00:00Z",  "updatedAt": "2024-06-15T12:00:00Z",  "links": [    {      "rel": "self",      "href": "/mailboxes/a1b2c3d4-e5f6-7890-abcd-ef1234567890"    }  ]}

Last updated on

How is this guide?