Skip to content

Change delegates

POST/mailboxes/{id}/delegates

Email Management API · Mailbox Management

Add and remove delegates of the mailbox.

Parameters

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

Request body

Content type: application/json

Request body fields

addarray of string
Add delegates of the mailbox.
Must contain at most 50 items.
removearray of string
Remove delegates of the mailbox.
Must contain at most 50 items.

Request samples

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


import requests

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


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

Responses

200 — All or few delegates updated.

Response fields

addedarray of string
Successfully added delegates of the mailbox.
removedarray of string
Successfully removed delegates of the mailbox.
errorsobject
Failed to add and remove from the mailbox.
Show child attributesHide child attributes
failedToAddarray of object
Failed to add.
Show child attributesHide child attributes
errorstringrequired
messagestring
correlationIdstring (uuid)
codestring
createdAtstring (datetime)
requestIdstring (uuid)
docUrlstring (uri)
failedToRemovearray of object
Failed to remove.
Show child attributesHide child attributes
errorstringrequired
messagestring
correlationIdstring (uuid)
codestring
createdAtstring (datetime)
requestIdstring (uuid)
docUrlstring (uri)

Errors

Status Meaning
400 Bad request.
404 Mailbox not found.
409 Directory synced mailbox.
500 Unexpected error.

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

Response examples

200

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