# How to list and look up mailboxes (https://developer.godaddy.com/en/docs/api-users/email/mailboxes/manage-mailboxes)

---
title: How to list and look up mailboxes
description: >-
  List mailboxes across your domains, filter and paginate the results, and look
  up a single mailbox.
keywords: >-
  list mailboxes, GET /v1/email/mailboxes, mailboxId, pageSize, totalRequired,
  field selection, Mailbox status
agentNotes:
  permissions:
    - Email mailbox management
  scopes:
    - 'email.mailbox:read'
  rateLimit: >-
    Rate-limited per credential per window. Go to /docs/api-users/rate-limits
    for current values.
  idempotent: true
  destructive: false
  failureRecovery: Read-only. Safe to retry.
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
  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 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](https://developer.godaddy.com/docs/references/rest/email/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](https://developer.godaddy.com/docs/api-users/auth) 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:

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

  ```js tab="Node"
  const res = await fetch("https://api.godaddy.com/v1/email/mailboxes", {
    headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` },
  });
  const mailboxes = await res.json();
  ```

  ```python tab="Python"
  import os, requests

  res = requests.get(
      "https://api.godaddy.com/v1/email/mailboxes",
      headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"},
  )
  mailboxes = res.json()
  ```

  ```go tab="Go"
  package main

  import (
  	"net/http"
  	"os"
  )

  func listMailboxes() (*http.Response, error) {
  	req, _ := http.NewRequest("GET", "https://api.godaddy.com/v1/email/mailboxes", nil)
  	req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT"))
  	return http.DefaultClient.Do(req)
  }
  ```

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

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

  ```js tab="Node"
  const status = "FAILED";
  const res = await fetch(
    `https://api.godaddy.com/v1/email/mailboxes?status=${status}`,
    { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } }
  );
  const mailboxes = await res.json();
  ```

  ```python tab="Python"
  import os, requests

  status = "FAILED"
  res = requests.get(
      "https://api.godaddy.com/v1/email/mailboxes",
      params={"status": status},
      headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"},
  )
  mailboxes = res.json()
  ```

  ```go tab="Go"
  package main

  import (
  	"net/http"
  	"os"
  )

  func listByStatus(status string) (*http.Response, error) {
  	req, _ := http.NewRequest("GET",
  		"https://api.godaddy.com/v1/email/mailboxes?status="+status, nil)
  	req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT"))
  	return http.DefaultClient.Do(req)
  }
  ```

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

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

  ```js tab="Node"
  const fields = "mailboxId,emailAddress,status";
  const res = await fetch(
    `https://api.godaddy.com/v1/email/mailboxes?field=${fields}`,
    { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } }
  );
  const mailboxes = await res.json();
  ```

  ```python tab="Python"
  import os, requests

  fields = "mailboxId,emailAddress,status"
  res = requests.get(
      "https://api.godaddy.com/v1/email/mailboxes",
      params={"field": fields},
      headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"},
  )
  mailboxes = res.json()
  ```

  ```go tab="Go"
  package main

  import (
  	"net/http"
  	"os"
  )

  func listFields(fields string) (*http.Response, error) {
  	req, _ := http.NewRequest("GET",
  		"https://api.godaddy.com/v1/email/mailboxes?field="+fields, nil)
  	req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT"))
  	return http.DefaultClient.Do(req)
  }
  ```

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

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

  ```js tab="Node"
  const res = await fetch(
    "https://api.godaddy.com/v1/email/mailboxes?totalRequired=true",
    { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } }
  );
  const mailboxes = await res.json();
  ```

  ```python tab="Python"
  import os, requests

  res = requests.get(
      "https://api.godaddy.com/v1/email/mailboxes",
      params={"totalRequired": "true"},
      headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"},
  )
  mailboxes = res.json()
  ```

  ```go tab="Go"
  package main

  import (
  	"net/http"
  	"os"
  )

  func listWithCounts() (*http.Response, error) {
  	req, _ := http.NewRequest("GET",
  		"https://api.godaddy.com/v1/email/mailboxes?totalRequired=true", nil)
  	req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT"))
  	return http.DefaultClient.Do(req)
  }
  ```

## Get a single mailbox

`GET /v1/email/mailboxes/{mailboxId}` returns one mailbox by ID. Go to [Provision a mailbox](https://developer.godaddy.com/docs/api-users/email/mailboxes/provision-mailboxes) for the polling procedure after mailbox creation.

The following procedure gets a single mailbox by ID.

* Get the mailbox:

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

  ```js tab="Node"
  const res = await fetch(
    `https://api.godaddy.com/v1/email/mailboxes/${process.env.MAILBOX_ID}`,
    { headers: { Authorization: `Bearer ${process.env.GODADDY_PAT}` } }
  );
  const mailbox = await res.json();
  ```

  ```python tab="Python"
  import os, requests

  res = requests.get(
      f"https://api.godaddy.com/v1/email/mailboxes/{os.environ['MAILBOX_ID']}",
      headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"},
  )
  mailbox = res.json()
  ```

  ```go tab="Go"
  package main

  import (
  	"net/http"
  	"os"
  )

  func getMailbox(mailboxID string) (*http.Response, error) {
  	req, _ := http.NewRequest("GET",
  		"https://api.godaddy.com/v1/email/mailboxes/"+mailboxID, nil)
  	req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT"))
  	return http.DefaultClient.Do(req)
  }
  ```

## Example responses

### List mailboxes

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

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

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

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

| Status | Most likely cause                                                                          | Recommended action                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid query parameter — for example, `pageSize` above `100`, or an unknown `field` name. | Inspect `details[]` in the error response.                                                                          |
| `403`  | Credential lacks `email.mailbox:read` scope.                                               | Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) to check required scopes.                                              |
| `404`  | `mailboxId` doesn't exist or isn't visible to this caller.                                 | Verify the `mailboxId`.                                                                                             |
| `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.