Skip to content

Add mailbox

POST/mailboxes

Email Management API · Mailbox Management

Add a new mailbox.

Parameters

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

Request body

Content type: application/json

Request body fields

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" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"type\": \"user\",
  \"email\": \"user@example.com\",
  \"name\": \"string\"
}"


import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/email/v1/mailboxes",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={'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 = '{
  "type": "user",
  "email": "user@example.com",
  "name": "string"
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/email/v1/mailboxes" -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", strings.NewReader(`{
  "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", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "type": "user",
  "email": "user@example.com",
  "name": "string"
}),
});
const data = await response.json();
console.log(data);

Responses

201 — A new mailbox is added.

Response fields

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.
409 Mailbox or alias already exists with email address.
500 Unexpected error.

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

Response examples

201

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