Manage Mailboxes using the API

Updated 1 month ago by admin

This article describes how to connect to the Platform API and manage Mailboxes as shown in the Email Security -> Mailboxes section.

You will need:

  • an admin user credential that has been assigned a Custom Role with the Manage Mailboxes ACL (see Role Builder and Administrators)
  • an admin user that does not have 2FA enabled but has a strong password set - this is to simplify the example below. 2FA can be implemented with additional API request if required, in addition to the scoped role in the first point
  • access to curl command (see external article for further information) - any programming language can be used however curl will be used for this example.

Authentication with the API

This example does not use 2FA however you can use the 2FA endpoints to complete the flow if required.

Copy and paste the following curl command and replace <USERNAME> and <PASSWORD> with the credential for your Agent Installer user.

curl --location 'https://apiv2.clouduss.com/auth' \
--form 'username="<USERNAME>"' \
--form 'password="<PASSWORD"'

If successful, you will receive a JSON response containing an access_token and accounts_id as shown below:

{
    "access_token": "879958cfxxxxxxxe90ad80a939a7",
    "token_type": "Bearer",
    "expires_in": 86400,
    "accounts_id": "b441390e-xxxx-xxxx-xxxx-36d7839f6153",
    ...all other metadata...
}

Copy the access_token and accounts_id for use in the next step.

Retrieving Mailboxes

To obtain the list of agents displayed in the Deployment view, use the following curl command with the access_token and accounts_idfrom the section Authenticating with the API:

curl --location 'https://apiv2.clouduss.com/email/mailbox/v2' \
--header 'X-Uss-Account-Id: <ACCOUNTS_ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

If successful, you will receive a JSON response containing all of the mailboxes registered to the account.

{
    "data": [
        {
            "id": 12182348,
            "email_address_id": 12503482,
            "email_address": "mailbox1@domain.com",
            "executive": 0,
            "realname": " ",
            "is_ad_mailbox": 1
        },
        {
            "id": 12636697,
            "email_address_id": 13717757,
            "email_address": "mailbox2@domain.com",
            "executive": 0,
            "realname": " ",
            "is_ad_mailbox": 1
        },
        ...all other results...
    ],
    "meta": {
        "page": 1,
        "page_size": 20,
        "total": 27,
        "total_pages": 2
    }
}

You can then copy and paste the response into online JSON parsing tools, such as JSON Grid (external link) or JSON to CSV (external link), and explore and manipulate the data further, e.g:

More advanced users can automate the use of the JSON data further with additional code and scripts.

Additional Options

You can also use the start and page parameters in the curl request to obtain more specific data.

The search parameter can be used to find matching mailboxes, example:

curl --location 'https://apiv2.clouduss.com/email/mailbox/v2?search=acme.com' \
--header 'X-Uss-Account-Id: <ACCOUNTS_ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

Add a Mailbox

To obtain the list of agents displayed in the Deployment view, use the following curl command with the access_token and accounts_idfrom Authenticating with the API:

curl -X POST https://apiv2.clouduss.com/email/mailbox \
--header 'X-Uss-Account-Id: <ACCOUNTS_ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data '[{"id":"USSportal.email.model.Mailbox-1","email_address_id":0,"executive":0,"email_address":"newuser@domain.com"}]'

Note that the only parameter you need to customise is email_address

Remove a Mailbox

To obtain the list of agents displayed in the Deployment view, use the following curl command with the access_token and accounts_idfrom Authenticating with the API and the id and email_address_id obtained from the section Retrieving Mailboxes above.

curl -X DELETE https://apiv2.clouduss.com/email/mailbox \
--header 'X-Uss-Account-Id: <ACCOUNTS_ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data '[{"id":12765948,"email_address_id":14028850,"email_address":"newuser@domain.com"}]'

How did we do?