# 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/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
---

## 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.