Skip to content

Getting started

Overview

This guide provides instructions on utilizing the Mailbox Management APIs in Sophos Email. It covers how to retrieve mailbox details and perform key actions such as creating, updating, searching, and deleting mailboxes, as well as raising a request to get bulk sender privileges.

Prerequisites

You must have a set of API credentials (service principal) to call the Mailbox APIs. For more information, refer to the appropriate quick start guide:

Terminology

Before you use the Mailbox Management APIs, here are a few terms you should know:

  • ID: The unique ID for the mailbox is a UUID string.

Making API requests

You can make the API calls in the next few sections using cURL. Follow the instructions on cURL's website to install this tool.

When you use curl, a request to the Mailbox Management API has the following general form:

curl -X <method> -H "Authorization: Bearer <jwt>" -H "X-Tenant-ID: <tenant-id>" <data-region>/<path>

The command includes the following placeholders:

  • <method>: The request method. For the Mailbox Management API, this is either GET, POST, PATCH, or DELETE.
  • <tenant-id>: The ID of the tenant you want to query.
  • <jwt>: The JWT access token is returned when the IDP authenticates the service principal.
  • <data-region>: The regional API host in the data geography where the tenant data is located.
  • <path>: The request path for the API operation, for example /email/v1/mailboxes.

The API descriptions in this guide only specify the request method and path. For example:

POST /email/v1/mailboxes

To make an actual API request, you must expand this to the full form.

All API requests return HTTP status codes 200 or 201 when successful.

Rate limit

The Mailbox Management API has rate limits in place. The rate limit quota is explained in the following section. If you exceed the rate limits, you’ll receive a 429 HTTP status code.

Rate limit quota

Each API has a defined rate limit to ensure fair usage and maintain system stability. The rate limits are set on a daily basis:

  • Daily Rate Limit: Maximum number of requests that can be made in a 24-hour period.

The specific daily limits for each API are as follows:

  • Create API: 10,000 requests per day
  • Update API: 10,000 requests per day
  • Delete API: 10,000 requests per day
  • Get API: 20,000 requests per day

Note: The hourly rate limit is the same as the daily limit. (Update API includes update of name, aliases, delegates, or distribution list owner)

To increase the rate limit quota, contact Sophos support.

Mailbox management operations

Create mailbox

Use this API to create a mailbox.

POST /email/v1/mailboxes

Request:

{
  "type": "user", //Type of the mailbox.
  "email": "johndoe@example.com", //Unique email id for the mailbox.
  "name" : "John Doe" //Name for the mailbox.

}

Response:

{
  "id": "1ed18881-6828-4c42-8b76-65ea57a98492", //Unique mailbox ID. It is a UUID string.
  "type": "user", //Type of the mailbox.
  "email": "johndoe@example.com",  //Email address of the mailbox.
  "name": "John Doe", //Name of the mailbox.
  "createdAt": "2024-09-13T06:00:08.785Z", //Timestamp at which mailbox was created in UTC.
  "bulkSenderPrivilege": {
    "bulkSenderPrivilegeStatus": "neverRequested" //Current status of bulk sender privilege of the mailbox.
  },
  "blocked": false //Current state of the mailbox.
}

Create mailboxes in bulk

Use this API to create multiple mailboxes in a single request. Single request supports a maximum of 10 mailboxes to be created.

POST /email/v1/mailboxes/bulk

Request:

{
  //Array contains details of the all the mailboxes to be created.
  "items": [
    {
      "type": "user", 
      "email": "user.name-1@example.com", 
      "name" : "user name 1" 

    },
    {
      "type": "user",
      "email": "user.name-2@example.com", 
      "name" : "user name 2"

    },
    {
      "type": "user",
      "email": "user.name-3@example.com", 
      "name" : "user name 3"

    }
  ]
}

Response:

{
  //Array contains response of Mailboxes created in bulk.
  "items": [
    {
      "id": "1ed18881-6828-4c42-8b76-65ea57a98492", 
      "type": "user",
      "email": "user.name-1@example.com",  
      "name": "user name 1",
      "createdAt": "2024-09-13T06:00:08.785Z", 
      "bulkSenderPrivilege": {
        "bulkSenderPrivilegeStatus": "neverRequested" 
      },
      "blocked": false 
    },
    {
      "id": "1ed18881-6828-4c42-8b76-65ea57a98492",
      "type": "user",
      "email": "user.name-2@example.com", 
      "name": "user name 2",
      "createdAt": "2024-09-13T06:00:08.785Z", 
      "bulkSenderPrivilege": {
        "bulkSenderPrivilegeStatus": "neverRequested"
      },
      "blocked": false
    }
  ],

  //Mailboxes detail for which mailbox creation failed due to an error.
  "errors": [
    {
      "error": "duplicateMailbox",
      "message": "user.name-3@example.com, A mailbox with the given email already exists"
    }
  ]

}

Delete mailboxes

Use this API to delete multiple mailboxes in a single request. Single request supports a maximum of 20 mailboxes to be deleted. If the API times out or an unexpected error occurs, some or all requested mailboxes might be deleted from the system. In such a case, check the mailbox detail by API or in Sophos Fusion to verify whether the mailbox has been deleted or not.

POST /email/v1/mailboxes/delete

Request:

{
  //Array contains mailbox ids to be deleted.
  "items": [
    {
      "id": "7761806c-9a7d-4689-a63f-03f5da54d1e7"
    },
    {
      "id": "6761806c-9a7d-4689-a63f-03f5da54d1e6"
    },
    {
      "id": "5761806c-9a7d-4689-a63f-03f5da54d1e5"
    }
  ]
}

Response:

{
  //List of Mailbox IDs of successfully deleted mailboxes.
  "items": [
    {
      "id": "7761806c-9a7d-4689-a63f-03f5da54d1e7"
    }
  ],

  //List of Mailbox IDs for which mailbox deletion failed.
  "errors": [
    {
      "id": "6761806c-9a7d-4689-a63f-03f5da54d1e6",
      "error": "idNotAvailable"
    },
    {
      "id": "5761806c-9a7d-4689-a63f-03f5da54d1e5",
      "error": "idNotAvailable"
    }
  ]
}

Delete mailbox by ID

Use this API to delete a specific mailbox using the mailbox ID.

DELETE /email/v1/mailboxes/{id}

Response:

{
    "deleted": true
}

Get mailbox by ID

Use this API to get details of the specific mailbox. It also provides information about the mailbox's aliases, delegates, and policies applied to the mailbox.

GET /email/v1/mailboxes/{id}

Response:

{
  "id": "1dd64bed-3e4c-4c79-964b-d86a6857b6b1", //Mailbox ID.
  "type": "user", //Type of the mailbox.
  "email":"johndoe@example.com", //Email address of the mailbox.
  "name" : "John Doe", //Name of the mailbox.
  "createdAt":"2024-02-12T11:35:16.169Z", //Timestamp at which the mailbox is created.
  "bulkSenderPrivilege": {
    "bulkSenderPrivilegeStatus": "neverRequested" //Current bulksender privilege status of the mailbox.
  },
  "blocked" : true //Current status of the mailbox.

  //If the mailbox type is distributionList then the array will have the list of its owners.
  "distributionListOwners" : [
    "owner@example.com"
  ],

  //Aliases of the mailbox.
  "aliases" : [
    "alias1@example.com",
    "alias2@example.com"
  ],

  //Delegates of the mailbox.
  "delegates" : [
    "delegate1@example.com",
    "delegate2@example.com"
  ],

  //Policies applied to the mailbox.
  "policies":
  {
    "emailSecurity": ["Block Spam", "base policy"],
    "dataControl": ["Block CCL", "base policy"],
    "secureMessage": ["Portal Encryption", "base policy"]
  }
}

List or search mailboxes

Use this API to list all or search mailboxes based on different parameters. Search parameters can be provided in query parameters. At a time, only one search parameter can be used.

GET /email/v1/mailboxes

List mailboxes with pagination:

GET /email/v1/mailboxes?name=John%20Doe&pageFromKey=15&pageSize=2

List mailboxes with pagination and search query:

GET /email/v1/mailboxes?nameStartsWith=John%20Doe&pageFromKey=15&pageSize=2

Supported search query parameters:

  • name: Retrieves all mailboxes with the specified name. This parameter is case-insensitive.
  • nameStartsWith: Retrieves all mailboxes with names that start with the specified query. This parameter is case-insensitive.
  • emailStartsWith: Retrieves all mailboxes with email addresses that start with the specified string. This parameter is case-insensitive.
  • createdAfter: Retrieves all mailboxes created after the specified time. The supported date format is yyyy-MM-dd, and the supported date and time format is yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
  • createdBefore: Retrieves all mailboxes created before the specified time. The supported date format is yyyy-MM-dd, the and supported date and time format is yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.
  • type: Retrieves all mailboxes of the specified type. Supported mailbox types are: user, distributionList, and publicFolder.
  • bulkSenderPrivilegeStatus: Retrieves all mailboxes with the specified bulk sender privilege status. Supported statuses are: neverRequested, approvalPending, approved, and rejected.
  • distributionListOwnedBy: Retrieves all mailboxes of the distribution list owned by a specified person. It supports the email address and name of the owner.
  • alias: Retrieves mailbox details that match the specified alias.
  • aliasesStartWith: Retrieves mailbox details where aliases begin with the specified string.
  • delegate: Retrieves mailbox details where the specified delegate email, provided as a query parameter, is assigned as a delegate.

Supported pagination query parameters:

  • pageFromKey: The nextKey nextKey retrieves subsequent records. By default, it’s set to 0. To fetch the next page of results, pass the nextKey value from the previous response.
  • pageSize: The pageSize key specifies the number of records in the response. A maximum of 50 records is supported.

Response:

{
  "pages": {
    "fromKey": "15", //Key which is passed as pageFromKey in the request.
    "nextKey": "17",//Value of pageFromKey to get the next page in subsequent request.
    "size": 2, //Requested pageSize.
    "maxSize": 50 //Maximum supported pageSize.
  },

  //Array contains list of mailboxes
  "items": [
    {
      "id": "09991ecd-7af1-4fcb-9446-71747ed163ad",
      "type": "user",
      "email": "jane.perry@example.com",
      "name": "Jane Perry",
      "createdAt": "2024-09-13T10:27:26.977Z",
      "bulkSenderPrivilege": {
        "bulkSenderPrivilegeStatus": "neverRequested"
      },
      "blocked": false,
      "aliases": [],
      "delegates": []
    },
    {
      "id": "bb8791cd-a46c-42d6-9430-b7f936db937d",
      "type": "user",
      "email": "johndoe@example.com",
      "name": "John Doe",
      "createdAt": "2024-09-13T10:27:27.240Z",
      "bulkSenderPrivilege": {
        "bulkSenderPrivilegeStatus": "neverRequested"
      },
      "blocked": false,
      "aliases": [],
      "delegates": []
    }
  ]
}

Generate request for bulk sender privilege

Use this API to generate a request for bulk sender privilege for the mailbox. The purpose of the requested data is to study the requirement only. The limit for bulk senders will be as per Bulk sender quota.

POST /email/v1/mailboxes/{id}/bulksender-privilege-request

Request:

{
  "count": 100000, //Count of emails sent per period.
  "period": "daily", //Period for which the count is specified.
  "purpose": "To send invoices" //Purpose for which the bulk sender privilege is required.
}

Response:

{
  "accepted": true
}

Update name of the mailbox

Use this API to update the name of the mailbox.

PATCH /email/v1/mailboxes/{id}

Request:

{
  "name": "johndoe"
}

Response:

{
  "id": "d9d9a0e9-d1b1-456d-a1fe-25f1e2d74584",
  "type": "user",
  "email": "johndoe@example.com",
  "name": "johndoe",
  "createdAt": "2024-09-13T05:58:45.679Z",
  "bulkSenderPrivilege": {
    "bulkSenderPrivilegeStatus": "neverRequested"
  },
  "blocked": false
}

Add or remove aliases of the mailbox

Use this API to add or remove aliases of the mailbox.

POST /email/v1/mailboxes/{id}/aliases

Request:

{
  //List of Aliases which will be added to the mailbox.
  "add": [
    "alias1@example.com",
    "alias2@example.com"
  ],

  //List of Aliases which will be removed from the mailbox.
  "remove": [
    "alias3@example.com",
    "alias4@example.com"
  ]
}

Response:

{
  //List of Aliases added to the mailbox.
  "added": [
    "alias1@example.com"
  ],

  //List of Aliases removed from the mailbox.
  "removed": [
    "alias3@example.com"
  ],

  "errors" : {
    //List of Aliases which where failed to be added.
    "failedToAdd" : [
      {
        "error": "duplicateMailbox",
        "message": "alias2@example.com, A mailbox with given email already exist"
      }
    ],

    //List of aliases which where failed to be removed.
    "failedToRemove" : [
      {
        "error": "aliasDoesNotExist",
        "message": "alias4@example.com does not exist"
      }
    ]
  }
}

Add or remove delegates of the mailbox

Use this API to add or remove delegates of the mailbox.

POST /email/v1/mailboxes/{id}/delegates

Request:

{
  //List of Aliases which will be added to the mailbox.
  "add": [
    "delegate1@example.com",
    "delegate2@example.com"
  ],

  //List of Aliases which will be removed from the mailbox.
  "remove": [
    "delegate3@example.com",
    "delegate4@example.com"
  ]
}

Response:

{
  //List of Delegates added to the mailbox.
  "added": [
    "delegate1@example.com"
  ],
  //List of Aliases removed from the mailbox.
  "removed": [
    "delegate3@example.com"
  ],
  "errors": {
    //List of Aliases which where failed to be added.
    "failedToAdd": [
      {
        "error": "delegateLimitExceeded",
        "message": "delegate4@example.com does not exist"
      }
    ],
    //List of aliases which where failed to be removed.
    "failedToRemove": [
      {
        "error": "mailboxNotFound",
        "message": "You are trying to update delegate with email address, delegate2@example.com, for which the mailbox does not exist."
      }
    ]
  }
}

Add or remove distribution list owner of the mailbox

Use this API to add or remove distribution list owners of the mailbox, if mailbox type is distributionList.

POST /email/v1/mailboxes/{id}/distribution-list-owners

{
  //List of Aliases which will be added to the mailbox.
  "add": [
    "distributionListOwner1@example.com"
  ],

  //List of Aliases which will be removed from the mailbox.
  "remove": [
    "distributionListOwner2@example.com"
  ]
}

Response:

{
  //optional
  "added": [
    "distributionListOwner1@example.com"
  ],

  "errors" : {
    "failedToRemove" : [
      {
        "error": "mailboxNotFound",
        "message": "distributionListOwner2@example.com does not exist"
      }
    ]
  }
}

Conclusion

See the Email Management API reference for a comprehensive description of this API.