GoDaddy
Support
API ReferenceMailboxes

Mailboxes

View as Markdown

List and provision email mailboxes for domains owned by the authenticated account. The collection endpoint returns a unified view across all supported email platforms. The create endpoint auto-selects the platform from the domain's entitlements.

Check if a mailbox can be provisioned

GET
/check-mailbox-eligibility

Authorization

AuthorizationBearer <token>

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

In: header

Query Parameters

email*string

Full email address to check (user@domain).

Formatemail

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

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/check-mailbox-eligibility?email=jane.smith%40example.com"

{  "isEligible": true,  "eligibleAccounts": [    {      "accountId": "00000000-0000-0000-0000-000000000002",      "mailboxType": "TITAN",      "accountName": "Professional Email Pro Plus",      "default": false,      "requirements": [        {          "type": "FREETRIAL_AUTORENEW",          "title": "Free Trial Auto Renew",          "reference": "https://www.godaddy.com/agreements/showdoc?pageid=FREETRIAL_AUTORENEW"        }      ]    }  ]}

Get a single mailbox by ID

GET
/mailboxes/{mailboxId}

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

mailboxId*string

The mailbox identifier returned from POST /mailboxes.

Formatuuid

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

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/mailboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "mailboxId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "emailAddress": "jane.smith@example.com",  "mailboxType": "TITAN",  "firstName": "Jane",  "lastName": "Smith",  "displayName": "Jane Smith",  "status": "COMPLETED",  "createdAt": "2024-03-15T10:30:00Z",  "updatedAt": "2024-06-01T08:00:00Z",  "links": [    {      "rel": "self",      "href": "/mailboxes/a1b2c3d4-e5f6-7890-abcd-ef1234567890"    }  ]}

List all email mailboxes

GET
/mailboxes

Authorization

bearerAuth
AuthorizationBearer <token>

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

In: header

Query Parameters

status?Mailbox Status

Filter mailboxes by operational status.

Value in

  • "EXECUTING"
  • "COMPLETED"
  • "FAILED"
  • "DELETED"
page?integer

Page number (1-based). Defaults to 1.

Range1 <= value
Default1
pageSize?integer

Number of mailboxes per page. Defaults to 25, maximum 100.

Range1 <= value <= 100
Default25
field?string

Comma-separated list of top-level Mailbox fields to include in each response object. When omitted, all fields are returned.

totalRequired?boolean

When true, includes totalItems and totalPages in the response body and adds a last navigation link.

Defaultfalse

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

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/mailboxes?status=COMPLETED&page=2&pageSize=25&field=mailboxId%2CemailAddress%2Cstatus&totalRequired=true"

{  "items": [    {      "mailboxId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",      "emailAddress": "jane.smith@example.com",      "mailboxType": "TITAN",      "firstName": "Jane",      "lastName": "Smith",      "displayName": "Jane Smith",      "status": "COMPLETED",      "createdAt": "2024-03-15T10:30:00Z",      "updatedAt": "2024-06-01T08:00:00Z"    },    {      "mailboxId": "a1b2c3d4-js80-7890-abcd-2kd23459hbsk",      "emailAddress": "john.doe@contoso.com",      "mailboxType": "TITAN",      "firstName": "John",      "lastName": "Doe",      "displayName": "John Doe",      "status": "COMPLETED",      "createdAt": "2024-04-10T09:00:00Z",      "updatedAt": "2024-06-01T08:00:00Z"    }  ],  "links": [    {      "rel": "self",      "href": "/mailboxes?page=2&pageSize=25"    },    {      "rel": "first",      "href": "/mailboxes?page=1&pageSize=25"    },    {      "rel": "next",      "href": "/mailboxes?page=3&pageSize=25"    },    {      "rel": "prev",      "href": "/mailboxes?page=1&pageSize=25"    }  ]}

Create a new email mailbox

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?