Skip to content

Query Mailboxes

GET/mailboxes

Email Management API · Mailbox Management

List all mailboxes or search mailboxes based on query parameter.

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
pageFromKey query string No The key of the item from where to fetch a page.
pageSize query integer No The size of the page requested.
name query string No Name of the mailbox.
nameStartsWith query string No Mailboxes where the name starts with the given string.
email query string (email) No Email address of the mailbox.
emailStartsWith query string No Mailboxes where the email address starts with the given string.
createdAfter query string (datetime) No Mailboxes created after the given date or date and time.
createdBefore query string (datetime) No Mailboxes created before the given date or date and time.
type query string No Mailbox type.
Must be one of: user, distributionList, publicFolder, sharedMailbox.
bulkSenderPrivilegeStatus query string No Bulk sender privilege status of the mailbox.
Must be one of: neverRequested, approvalPending, approved, rejected, revoked.
blocked query boolean No Status of the mailbox.
distributionListOwnedBy query string No Name or email address of the distribution list owner to find the distribution list mailboxes owned by the mailbox.
alias query string (email) No Mailbox of specified alias.
aliasesStartWith query string No Mailboxes where the alias starts with the given string.
delegate query string (email) No Email address of the mailbox to find delegated mailbox.

Request samples

curl -X GET "https://api-<data-region>.central.sophos.com/email/v1/mailboxes" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>"


import requests

response = requests.get(
    "https://api-<data-region>.central.sophos.com/email/v1/mailboxes",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
    },
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
}
Invoke-RestMethod -Method GET -Uri "https://api-<data-region>.central.sophos.com/email/v1/mailboxes" -Headers $headers


package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, err := http.NewRequest("GET", "https://api-<data-region>.central.sophos.com/email/v1/mailboxes", nil)
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}


const response = await fetch("https://api-<data-region>.central.sophos.com/email/v1/mailboxes", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
  },
});
const data = await response.json();
console.log(data);

Responses

200 — List of mailboxes.

Response fields

pagesobject
Show child attributesHide child attributes
fromKeystring
The key of the first item in the returned page.
nextKeystring
The key to use when fetching the next page.
sizeintegerrequired
The size of the page being returned.
maxSizeintegerrequired
The maximum page size that can be requested.
itemsarray of object
List of mailboxes.
Mailbox.
Show child attributesHide child attributes
idstring (uuid)required
Mailbox ID.
typestringrequired
Mailbox type.
Must be one of: user, distributionList, publicFolder, sharedMailbox.
emailstringrequired
Email address.
namestringrequired
Name.
createdAtstring (date-time)required
Creation date of the mailbox, in ISO 8601 format.
bulkSenderPrivilegeobject
Bulk sender privilege.
Show child attributesHide child attributes
bulkSenderPrivilegeStatusstringrequired
Bulk sender privilege status of the mailbox.
Must be one of: neverRequested, approvalPending, approved, rejected, revoked.
blockedbooleanrequired
Status of the mailbox.
distributionListOwnersarray of string
Owners of the distribution list mailbox.
aliasesarray of string
Aliases of the mailbox.
delegatesarray of string
Delegates of the mailbox.
policiesobject
Policies applied to the mailbox.
Show child attributesHide child attributes
emailSecurityarray of stringrequired
Email security policies applied to the mailbox.
dataControlarray of stringrequired
Data control policies applied to the mailbox.
secureMessagearray of stringrequired
Secure message policies applied to the mailbox.

Errors

Status Meaning
400 Bad request.
500 Internal server error.

All error responses share the same shape — see the error response object.

Response examples

200

{
  "pages": {
    "fromKey": "string",
    "nextKey": "string",
    "size": 0,
    "maxSize": 0
  },
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "type": "user",
      "email": "string",
      "name": "string",
      "createdAt": "2026-07-28T00:00:00Z",
      "bulkSenderPrivilege": {
        "bulkSenderPrivilegeStatus": "approved"
      },
      "blocked": true,
      "distributionListOwners": [
        "string"
      ],
      "aliases": [
        "string"
      ],
      "delegates": [
        "string"
      ],
      "policies": {
        "emailSecurity": [
          "John Doe policy",
          "Base Policy"
        ],
        "dataControl": [
          "Block credit card",
          "Base Policy"
        ],
        "secureMessage": [
          "Base Policy"
        ]
      }
    }
  ]
}

See the guide for a narrative walkthrough of this API.