How to list and look up mailboxes

Overview

This guide covers listing mailboxes across the domains an account owns, filtering and paginating the results, and looking up a single mailbox by ID.

GET /v1/email/mailboxes returns all mailboxes across account-owned domains in a single paginated response. Use page and pageSize to navigate; follow the next and prev links in the response rather than constructing URLs. Filter by status, select specific fields with field, or add totalRequired=true to include total counts. Requesting counts costs an extra query, so leave it off unless the caller needs it.

GET /v1/email/mailboxes/{mailboxId} returns a single mailbox by ID. Go to Email API — Mailboxes for all available query parameters and response schemas.

Prerequisites

The following prerequisites are required before you can list and look up mailboxes.

• a PAT with email.mailbox:read scope

List mailboxes

GET /v1/email/mailboxes returns mailboxes across all domains the authenticated account owns, in a single unified view.

The following procedure lists mailboxes.

• List mailboxes:

  curlNodePythonGo

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

Filter by status

status filters the list to mailboxes in a single state — useful for finding mailboxes still provisioning or ones that failed.

The following procedure filters mailboxes by status.

• Filter by status:

  curlNodePythonGo

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

Select specific fields

field returns only the top-level Mailbox fields you name. Omitting it returns all fields.

The following procedure requests specific fields.

• Select fields:

  curlNodePythonGo

  curl -s "https://api.godaddy.com/v1/email/mailboxes?field=mailboxId,emailAddress,status" \
    -H "Authorization: Bearer $GODADDY_PAT"

Get total counts

totalRequired=true adds totalItems and totalPages to the response and a last link for jumping to the final page.

The following procedure requests total counts.

• Get total counts:

  curlNodePythonGo

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

Get a single mailbox

GET /v1/email/mailboxes/{mailboxId} returns one mailbox by ID. Go to Provision a mailbox for the polling procedure after mailbox creation.

The following procedure gets a single mailbox by ID.

• Get the mailbox:

  curlNodePythonGo

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

Example responses

List mailboxes

GET /v1/email/mailboxes returns a paginated items array with links for navigation:

{
  "items": [
    {
      "mailboxId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "emailAddress": "jane.smith@example.com",
      "mailboxType": "TITAN",
      "status": "COMPLETED",
      "links": [...]
    }
  ],
  "links": [
    { "rel": "self", "href": "/v1/email/mailboxes?page=1&pageSize=25" },
    { "rel": "next", "href": "/v1/email/mailboxes?page=2&pageSize=25" }
  ]
}

When totalRequired=true, the response also includes totalItems, totalPages, and a last link:

{
  "items": [
    { "mailboxId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "emailAddress": "jane.smith@example.com", "mailboxType": "TITAN", "status": "COMPLETED" }
  ],
  "totalItems": 100,
  "totalPages": 4,
  "links": [
    { "rel": "self", "href": "/v1/email/mailboxes?page=1&pageSize=25" },
    { "rel": "next", "href": "/v1/email/mailboxes?page=2&pageSize=25" },
    { "rel": "last", "href": "/v1/email/mailboxes?page=4&pageSize=25" }
  ]
}

Get a single mailbox

GET /v1/email/mailboxes/{mailboxId} returns the full Mailbox object:

{
  "mailboxId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "emailAddress": "jane.smith@example.com",
  "mailboxType": "TITAN",
  "firstName": "Jane",
  "lastName": "Smith",
  "displayName": "Jane Smith",
  "status": "COMPLETED",
  "createdAt": "2024-03-15T10:30:00Z",
  "updatedAt": "2024-06-01T08:00:00Z",
  "links": [
    { "rel": "self", "href": "/v1/email/mailboxes/a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
  ]
}

Common errors

The following table lists common errors and recommended actions:

Go to Handle errors for the full error envelope.

Last updated on