Skip to content

Add mailboxes

POST/mailboxes/bulk

Email Management API · Mailbox Management

Request to add multiple mailboxes.

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.

Request body

Content type: application/json

Request body fields

itemsarray of objectrequired
List of new mailboxes.
Must contain at most 10 items.
Add a new mailbox.
Show child attributesHide child attributes
typestringrequired
Mailbox type.
Must be one of: user, distributionList, publicFolder, sharedMailbox.
emailstring (email)required
Email address.
Must be 4–320 characters long.
namestringrequired
Name.
Must be 1–256 characters long.

Request samples

curl -X POST "https://api-<data-region>.central.sophos.com/email/v1/mailboxes/bulk" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"items\": [
    {
      \"type\": \"user\",
      \"email\": \"user@example.com\",
      \"name\": \"string\"
    }
  ]
}"


import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/email/v1/mailboxes/bulk",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={'items': [{'type': 'user', 'email': 'user@example.com', 'name': 'string'}]},
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "items": [
    {
      "type": "user",
      "email": "user@example.com",
      "name": "string"
    }
  ]
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/email/v1/mailboxes/bulk" -Headers $headers -Body $body -ContentType "application/json"


package main

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

func main() {
    req, err := http.NewRequest("POST", "https://api-<data-region>.central.sophos.com/email/v1/mailboxes/bulk", strings.NewReader(`{
  "items": [
    {
      "type": "user",
      "email": "user@example.com",
      "name": "string"
    }
  ]
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")
    req.Header.Set("Content-Type", "application/json")

    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/bulk", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "items": [
    {
      "type": "user",
      "email": "user@example.com",
      "name": "string"
    }
  ]
}),
});
const data = await response.json();
console.log(data);

Responses

201 — All or few mailboxes are added.

Response fields

itemsarray of object
List of successfully added 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.
errorsarray of object
List of items for which mailbox addition failed.
Show child attributesHide child attributes
errorstringrequired
messagestring
correlationIdstring (uuid)
codestring
createdAtstring (datetime)
requestIdstring (uuid)
docUrlstring (uri)

Errors

Status Meaning
400 Bad request.
500 Unexpected error.

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

Response examples

201

{
  "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"
        ]
      }
    }
  ],
  "errors": [
    {
      "error": "string",
      "message": "string",
      "correlationId": "00000000-0000-0000-0000-000000000000",
      "code": "string",
      "createdAt": "string",
      "requestId": "00000000-0000-0000-0000-000000000000",
      "docUrl": "https://example.com"
    }
  ]
}

See the guide for a narrative walkthrough of this API.