Skip to main content

Manage mailboxes through API

This article provides information on how to use APIs to manage mailboxes in the Email Security console.

Tip

You can also manage mailboxes from the Mailboxes page in the Email Security console.

Prerequisites

  • Contact support and request the following:

    • An Email Security user account that has been assigned a Custom role.

    • A username and password for API authentication.

  • An Email Security administrator account that does not have 2FA enabled. The account should have a strong login password set up.

    Tip

    2FA can be implemented with an additional API request if required.

  • A username and password to use in API authentication.

  • The ability to run curl commands or any other equivalent programming language.

    For the purpose of this article we will use curl commands.

Authentication

To authenticate, use the below request. Use the username and password received from support.

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

If the request is successful, you will receive a JSON response containing an access_token and accounts_id. Copy the two values for later use.

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

Retrieve managed mailboxes

Use the below request to get a list of all managed mailboxes in Email Security. Use the access_token and accounts_id parameters for authentication. 

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>'

Note

The search parameter is optional. You can use it to retrieve information on a specific mailbox.

If the request is successful, the information is returned in the below format.

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

Note

You can manually change the information of the mailboxes either directly in the code, using JSON parsing tools, or automatically using code, or scripts.

Add a Mailbox

To add a mailbox to the Email Security console use this request. Use the access_token and accounts_id parameters for authentication.

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":"[email protected]"}]'

Remove a Mailbox

To add a mailbox to the Email Security console use this request. Use the access_token and accounts_id parameters for authentication.

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":"[email protected]"}]'
In this section: