# About the Email API (https://developer.godaddy.com/en/docs/api-users/email)

---
title: About the Email API
description: >-
  How the Email API is structured, how mailbox provisioning works, and how the
  core resources relate to each other.
keywords: >-
  mailbox provisioning, Titan email, mailboxId, check-mailbox-eligibility,
  Idempotency-Key, email hosting API, provision mailbox, list mailboxes
related:
  apis:
    - title: Email API — Mailboxes
      href: /docs/references/rest/email/list-mailboxes
  guides:
    - title: Provision a mailbox
      href: /docs/api-users/email/mailboxes/provision-mailboxes
    - title: List and look up mailboxes
      href: /docs/api-users/email/mailboxes/manage-mailboxes
  concepts:
    - title: Authentication
      href: /docs/api-users/auth
    - title: Handle errors
      href: /docs/api-users/errors
pageId: 29dec047-fa1d-4a20-96fe-3dcb92fb1c3b
---

## Overview

The Email API provisions and manages email mailboxes for domains owned by the authenticated account. All paths are under `/v1/email/`, and every operation is scoped to domains the calling account already owns. There's no separate step to associate a domain first.

The API exposes a single core resource, `Mailbox`, plus an eligibility check that tells you whether a mailbox can be provisioned for a given address before you attempt to create one.

## How mailbox creation works

Creating a mailbox is asynchronous. `POST /v1/email/mailboxes` returns `202 Accepted` with the mailbox in its initial state (`status: EXECUTING`). Poll `GET /v1/email/mailboxes/{mailboxId}` until `status` reaches `COMPLETED` or `FAILED`.

`EXECUTING`, `COMPLETED`, `FAILED`, and `DELETED` are the valid statuses for a mailbox. Go to [Provision a mailbox](https://developer.godaddy.com/docs/api-users/email/mailboxes/provision-mailboxes) for the full polling procedure.

## The Mailbox object

The following table describes the fields of the `Mailbox` object:

| Field                     | Description                                                | Note                                                                                                           |
| ------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `mailboxId`               | Unique identifier for the mailbox.                         | Returned from `POST /v1/email/mailboxes`, used as the path parameter on `GET /v1/email/mailboxes/{mailboxId}`. |
| `emailAddress`            | Mailbox email address.                                     |                                                                                                                |
| `mailboxType`             | Underlying email platform.                                 | For example, `TITAN`. Auto-selected from the domain's entitlements at creation (you don't choose it).          |
| `firstName` / `lastName`  | Mailbox owner's name.                                      |                                                                                                                |
| `displayName`             | Display name shown to recipients.                          |                                                                                                                |
| `status`                  | Provisioning status.                                       | `EXECUTING`, `COMPLETED`, `FAILED`, or `DELETED`.                                                              |
| `createdAt` / `updatedAt` | ISO 8601 timestamps.                                       |                                                                                                                |
| `links`                   | Hypermedia links related to the mailbox, including `self`. |                                                                                                                |

## Eligibility, entitlements, and consents

Before the platform can provision a mailbox, three conditions must align. The address must be eligible, the account must have an entitlement (a provisioning credit tied to the domain), and any requirements on that entitlement must be consented to.

Call `GET /v1/email/check-mailbox-eligibility` to evaluate all three before attempting `POST /v1/email/mailboxes`. The response is an `EligibilityResult`:

| Field              | Description                                                     | Note                                                                            |
| ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `isEligible`       | Whether a mailbox can be provisioned for the requested address. | When `false`, the API returns an error response with details.                   |
| `eligibleAccounts` | Entitlements available to provision with.                       | Each entry has `accountId`, `mailboxType`, `accountName`, and a `default` flag. |

An entitlement might carry `requirements` (conditions the caller must accept before provisioning). A free-trial entitlement, for example, might require `FREETRIAL_AUTORENEW` consent. Pass any requirements as `consents` in the `POST /v1/email/mailboxes` request body. The created mailbox includes the accepted consents as `agreements`.

Go to [Provision a mailbox](https://developer.godaddy.com/docs/api-users/email/mailboxes/provision-mailboxes) for the full request and response shapes.

## OAuth scopes

The following table lists the OAuth scopes required for managing email mailboxes. Request only the scopes your integration needs.

| Scope                  | What it grants                                                         |
| ---------------------- | ---------------------------------------------------------------------- |
| `email.mailbox:read`   | List email mailboxes for domains owned by the authenticated account.   |
| `email.mailbox:create` | Create email mailboxes for domains owned by the authenticated account. |

Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) for how to generate a PAT with these scopes.