# Mailboxes (https://developer.godaddy.com/en/docs/references/rest/email/mailboxes) --- title: Mailboxes description: > 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. full: true --- ## GET /check-mailbox-eligibility Check if a mailbox can be provisioned Determines whether a mailbox can be provisioned for the given email address and which entitlements are available to use. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `email` | string | yes | Full email address to check (user@domain). | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Optional client-generated request correlation identifier. Propagated across services and echoed in the X-Request-Id response header. | ### Responses **200** — Eligibility result for the requested email address. Content-Type: `application/json` ```json { "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" } ] } ] } ``` Schema: - schema reference: `#/components/schemas/EligibilityResult` **400** — Malformed request syntax, missing required field, or invalid field value. Content-Type: `application/json` ```json { "name": "INVALID_INPUT", "correlationId": "req-abc-123", "message": "The provided request is invalid.", "details": [ { "field": "/username", "issue": "PATTERN_VIOLATION", "location": "body", "description": "Username must contain only letters, digits, dots, underscores, hyphens, and plus signs.\n" } ] } ``` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — The address is not eligible for mailbox provisioning. Check details[] in the response for the specific reason. Content-Type: `application/json` ```json { "name": "ELIGIBILITY_FAILURE", "correlationId": "7f3a9c21-5d84-4e67-b912-3a8f6c2d104e", "message": "Found 1 reason why this email address cannot be provisioned.", "details": [ { "issue": "EMAIL_PLAN_NOT_AVAILABLE", "description": "You need to purchase an email plan to create an email address." } ] } ``` Schema: - schema reference: `#/components/schemas/EligibilityError` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## GET /mailboxes/{mailboxId} Get a single mailbox by ID Returns the current state of a single mailbox. Poll this endpoint after POST /mailboxes until status reaches COMPLETED or FAILED. ### Path parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `mailboxId` | string | yes | The mailbox identifier returned from POST /mailboxes. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Optional client-generated request correlation identifier. Propagated across services and echoed in the X-Request-Id response header. | ### Responses **200** — The requested mailbox. Content-Type: `application/json` ```json { "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" } ] } ``` Schema: - schema reference: `#/components/schemas/Mailbox` **400** — Malformed request syntax, missing required field, or invalid field value. Content-Type: `application/json` ```json { "name": "INVALID_INPUT", "correlationId": "req-abc-123", "message": "The provided request is invalid.", "details": [ { "field": "/username", "issue": "PATTERN_VIOLATION", "location": "body", "description": "Username must contain only letters, digits, dots, underscores, hyphens, and plus signs.\n" } ] } ``` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **404** — The requested resource was not found. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## GET /mailboxes List all email mailboxes Returns a paged list of email mailboxes for domains owned by the authenticated account, across all supported email platforms. ### Query parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `status` | unknown | no | Filter mailboxes by operational status. | | `page` | integer | no | Page number (1-based). Defaults to 1. | | `pageSize` | integer | no | Number of mailboxes per page. Defaults to 25, maximum 100. | | `field` | string | no | Comma-separated list of top-level Mailbox fields to include in each response object. When omitted, all fields are returned. | | `totalRequired` | boolean | no | When true, includes totalItems and totalPages in the response body and adds a last navigation link. | ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Optional client-generated request correlation identifier. Propagated across services and echoed in the X-Request-Id response header. | ### Responses **200** — Paged list of mailboxes. Content-Type: `application/json` ```json { "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" } ] } ``` Schema: - schema reference: `#/components/schemas/MailboxList` **400** — Malformed request syntax, missing required field, or invalid field value. Content-Type: `application/json` ```json { "name": "INVALID_INPUT", "correlationId": "req-abc-123", "message": "The provided request is invalid.", "details": [ { "field": "/username", "issue": "PATTERN_VIOLATION", "location": "body", "description": "Username must contain only letters, digits, dots, underscores, hyphens, and plus signs.\n" } ] } ``` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`. ## POST /mailboxes Create a new email mailbox 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. ### Header parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `X-Request-Id` | string | no | Optional client-generated request correlation identifier. Propagated across services and echoed in the X-Request-Id response header. | | `Idempotency-Key` | string | yes | Client-generated unique key (UUID recommended). Retrying a POST request with the same Idempotency-Key returns the original response without creating a duplicate mailbox. | ### Request body (required) Content-Type: `application/json` ```json { "emailAddress": "jane.smith@example.com", "accountId": "00000000-0000-0000-0000-000000000001", "firstName": "Jane", "lastName": "Smith", "consents": [ { "type": "FREETRIAL_AUTORENEW" } ] } ``` Schema: - allOf(unknown & object) ### Responses **202** — Mailbox provisioning accepted. Content-Type: `application/json` ```json { "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" } ] } ``` Schema: - allOf(unknown & object) **400** — Malformed request syntax, missing required field, or invalid field value. Content-Type: `application/json` ```json { "name": "INVALID_INPUT", "correlationId": "req-abc-123", "message": "The provided request is invalid.", "details": [ { "field": "/username", "issue": "PATTERN_VIOLATION", "location": "body", "description": "Username must contain only letters, digits, dots, underscores, hyphens, and plus signs.\n" } ] } ``` Schema: - schema reference: `#/components/schemas/Error` **401** — Authentication credentials are missing or invalid. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **403** — Authenticated identity is not authorized to perform this operation. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **409** — Conflict — a mailbox with the requested email address already exists for this domain. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **422** — The address is not eligible for mailbox provisioning. Check details[] in the response for the specific reason. Content-Type: `application/json` ```json { "name": "ELIGIBILITY_FAILURE", "correlationId": "7f3a9c21-5d84-4e67-b912-3a8f6c2d104e", "message": "Found 1 reason why this email address cannot be provisioned.", "details": [ { "issue": "EMAIL_PLAN_NOT_AVAILABLE", "description": "You need to purchase an email plan to create an email address." } ] } ``` Schema: - schema reference: `#/components/schemas/EligibilityError` **429** — Too many requests — rate limit exceeded. Content-Type: `application/json` Schema: - schema reference: `#/components/schemas/Error` **Security:** requires `bearerAuth`.