How to provision a mailbox

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 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 for the status flow diagram.

Prerequisites

The following prerequisites are required before you can provision a mailbox.

• a PAT 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:

   curlNodePythonGo

   curl -s "https://api.godaddy.com/v1/email/check-mailbox-eligibility?email=$EMAIL_ADDRESS" \
     -H "Authorization: Bearer $GODADDY_PAT"

   Stop on 422

   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:

   curlNodePythonGo

   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\" }]
     }"

3. Poll for completion:

   curlNodePythonGo

   curl -s "https://api.godaddy.com/v1/email/mailboxes/$MAILBOX_ID" \
     -H "Authorization: Bearer $GODADDY_PAT"

Example responses

The following sections provide example responses for the mailbox provisioning API.

Check eligibility

GET /v1/email/check-mailbox-eligibility returns an EligibilityResult:

{
  "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:

{
  "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:

Go to Handle errors for the full error envelope.

Last updated on