# How to provision a mailbox (https://developer.godaddy.com/en/docs/api-users/email/mailboxes/provision-mailboxes) --- title: How to provision a mailbox description: >- Check eligibility, create a mailbox, and poll until it's ready, using the GoDaddy Email API. keywords: >- create mailbox, check-mailbox-eligibility, POST /v1/email/mailboxes, Idempotency-Key, mailbox provisioning, Titan email, EXECUTING COMPLETED FAILED, eligibleAccounts agentNotes: permissions: - Email mailbox management scopes: - 'email.mailbox:read' - 'email.mailbox:create' rateLimit: >- Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values. idempotent: true destructive: false failureRecovery: >- POST /mailboxes requires an Idempotency-Key header. Retrying with the same key returns the original response instead of creating a duplicate mailbox. related: apis: - title: Email API — Mailboxes href: /docs/references/rest/email/mailboxes guides: - title: List and look up mailboxes href: /docs/api-users/email/mailboxes/manage-mailboxes concepts: - title: About the Email API href: /docs/api-users/email - title: Authentication href: /docs/api-users/auth - title: Handle errors href: /docs/api-users/errors --- ## Overview This guide covers provisioning a mailbox using the GoDaddy Email API. Start with an eligibility check. `GET /v1/email/check-mailbox-eligibility` tells you whether the address can be provisioned and which entitlements are available. Some entitlements carry requirements the caller must consent to before provisioning (like a free-trial auto-renewal agreement); if those are present, include matching `consents` in the create request. Go to [Email API — Mailboxes](https://developer.godaddy.com/docs/references/rest/email/mailboxes) for the full request body schema including `consents`. Mailbox creation is asynchronous. `POST /v1/email/mailboxes` accepts the configuration and returns `202 Accepted` immediately, then provisions the mailbox in the background. Include an `Idempotency-Key` header on every create request so that retrying a failed call returns the original response instead of creating a duplicate. After creation, poll `GET /v1/email/mailboxes/{mailboxId}` until `status` reaches `COMPLETED` or `FAILED`. Go to [About the Email API](https://developer.godaddy.com/docs/api-users/email#how-mailbox-creation-works) for the status flow diagram. ## Prerequisites The following prerequisites are required before you can provision a mailbox. * a [PAT](https://developer.godaddy.com/docs/api-users/auth) with `email.mailbox:create` scope * an email address on a domain the authenticated account owns ## Provision a mailbox The following procedure provisions a mailbox. 1. Check whether the email address is eligible: ```bash tab="curl" curl -s "https://api.godaddy.com/v1/email/check-mailbox-eligibility?email=$EMAIL_ADDRESS" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" const res = await fetch( `https://api.godaddy.com/v1/email/check-mailbox-eligibility?email=${encodeURIComponent(process.env.EMAIL_ADDRESS)}`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } } ); const eligibility = await res.json(); ``` ```python tab="Python" import os, requests res = requests.get( "https://api.godaddy.com/v1/email/check-mailbox-eligibility", params={"email": os.environ["EMAIL_ADDRESS"]}, headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) eligibility = res.json() ``` ```go tab="Go" package main import ( "net/http" "net/url" "os" ) func checkEligibility() (*http.Response, error) { u := "https://api.godaddy.com/v1/email/check-mailbox-eligibility?" + url.Values{"email": {os.Getenv("EMAIL_ADDRESS")}}.Encode() req, _ := http.NewRequest("GET", u, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) return http.DefaultClient.Do(req) } ``` If the eligibility check returns `422`, the address is not eligible for provisioning. Check `details[]` in the response body for the reason — for example, `EMAIL_PLAN_NOT_AVAILABLE`. Don't attempt to create the mailbox. 2. Create the mailbox: ```bash tab="curl" curl -s -X POST "https://api.godaddy.com/v1/email/mailboxes" \ -H "Authorization: Bearer $GODADDY_PAT" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{ \"emailAddress\": \"$EMAIL_ADDRESS\", \"accountId\": \"$ACCOUNT_ID\", \"firstName\": \"$FIRST_NAME\", \"lastName\": \"$LAST_NAME\", \"consents\": [{ \"type\": \"FREETRIAL_AUTORENEW\" }] }" ``` ```js tab="Node" const res = await fetch("https://api.godaddy.com/v1/email/mailboxes", { method: "POST", headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}`, "Idempotency-Key": crypto.randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ emailAddress: process.env.EMAIL_ADDRESS, accountId: process.env.ACCOUNT_ID, firstName: process.env.FIRST_NAME, lastName: process.env.LAST_NAME, consents: [{ type: "FREETRIAL_AUTORENEW" }], }), }); const mailbox = await res.json(); ``` ```python tab="Python" import os, uuid, requests res = requests.post( "https://api.godaddy.com/v1/email/mailboxes", headers={ "Authorization": f"Bearer {os.environ['GODADDY_PAT']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "emailAddress": os.environ["EMAIL_ADDRESS"], "accountId": os.environ["ACCOUNT_ID"], "firstName": os.environ["FIRST_NAME"], "lastName": os.environ["LAST_NAME"], "consents": [{"type": "FREETRIAL_AUTORENEW"}], }, ) mailbox = res.json() ``` ```go tab="Go" package main import ( "bytes" "encoding/json" "net/http" "os" "github.com/google/uuid" ) func createMailbox() (*http.Response, error) { body, _ := json.Marshal(map[string]any{ "emailAddress": os.Getenv("EMAIL_ADDRESS"), "accountId": os.Getenv("ACCOUNT_ID"), "firstName": os.Getenv("FIRST_NAME"), "lastName": os.Getenv("LAST_NAME"), "consents": []map[string]string{{"type": "FREETRIAL_AUTORENEW"}}, }) req, _ := http.NewRequest("POST", "https://api.godaddy.com/v1/email/mailboxes", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) req.Header.Set("Idempotency-Key", uuid.NewString()) req.Header.Set("Content-Type", "application/json") return http.DefaultClient.Do(req) } ``` 3. Poll for completion: ```bash tab="curl" curl -s "https://api.godaddy.com/v1/email/mailboxes/$MAILBOX_ID" \ -H "Authorization: Bearer $GODADDY_PAT" ``` ```js tab="Node" async function pollMailbox(mailboxId, intervalMs = 3000) { while (true) { const res = await fetch( `https://api.godaddy.com/v1/email/mailboxes/${mailboxId}`, { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } } ); const mailbox = await res.json(); if (mailbox.status === "COMPLETED") return mailbox; if (mailbox.status === "FAILED") throw new Error("Mailbox provisioning failed"); await new Promise((r) => setTimeout(r, intervalMs)); } } ``` ```python tab="Python" import os, time, requests def poll_mailbox(mailbox_id, interval=3): while True: res = requests.get( f"https://api.godaddy.com/v1/email/mailboxes/{mailbox_id}", headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"}, ) mailbox = res.json() if mailbox["status"] == "COMPLETED": return mailbox if mailbox["status"] == "FAILED": raise RuntimeError("Mailbox provisioning failed") time.sleep(interval) ``` ```go tab="Go" package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) func pollMailbox(mailboxID string) { for { req, _ := http.NewRequest("GET", "https://api.godaddy.com/v1/email/mailboxes/"+mailboxID, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT")) res, _ := http.DefaultClient.Do(req) var mailbox struct { Status string `json:"status"` } json.NewDecoder(res.Body).Decode(&mailbox) res.Body.Close() switch mailbox.Status { case "COMPLETED": fmt.Println("Mailbox ready") return case "FAILED": panic("Mailbox provisioning failed") } time.Sleep(3 * time.Second) } } ``` ## Example responses The following sections provide example responses for the mailbox provisioning API. ### Check eligibility `GET /v1/email/check-mailbox-eligibility` returns an `EligibilityResult`: ```json { "isEligible": true, "eligibleAccounts": [ { "accountId": "00000000-0000-0000-0000-000000000001", "mailboxType": "TITAN", "accountName": "Professional Email", "default": true, "requirements": [] } ] } ``` ### Create a mailbox `POST /v1/email/mailboxes` returns the new `Mailbox` object: ```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" } ] } ``` The response includes a `Location` header pointing at the new mailbox resource. The `agreements` field reflects the `consents` submitted in the request body. ## Common errors The following table lists common errors and recommended actions: | Status | Most likely cause | Recommended action | | ------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `400` | Malformed request body, missing required field, or invalid `email` query parameter. | Inspect `details[]` in the error response. | | `403` | Credential lacks the required scope, or the domain isn't owned by the authenticated account. | Check `name` in the error response to distinguish. | | `404` | `mailboxId` doesn't exist or isn't visible to this caller. | Verify the `mailboxId` from the create response. | | `409` | A mailbox already exists for the requested email address on this domain. | Look up the existing mailbox instead of creating a new one. | | `422` | No available entitlements for the domain, or an unsupported domain type. | Run the eligibility check before retrying. | | `429` | Rate limit exceeded. | Wait, then retry. Go to [Handle rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for current limits and handling guidance. | Go to [Handle errors](https://developer.godaddy.com/docs/api-users/errors) for the full error envelope.