# Create a new email mailbox (https://developer.godaddy.com/en/docs/references/rest/email/create-mailbox)

---
title: Create a new email mailbox
description: >-
  Provisions a new email mailbox for a domain owned by the authenticated
  account.
full: true
---

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

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 <uuid> | 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`.