Subaccounts

Deprecation of non-paginated results: All results returned from the GET /api/v1/subaccounts endpoint will be paginated by default starting March 2022. Set thecursor parameter to initial to test paginated results.

Subaccounts are a way for you to provision and manage senders separately from each other, and to provide assets and reporting data for each of them. This is useful for service providers who send on behalf of others or for a business that wants to separate their different streams of traffic. Learn more in our subaccount guide.

The following APIs have subaccount support:

Note: all subaccount-level transmissions must use inline recipients. Stored recipient lists are not supported for subaccounts.

Terminology


Primary account	This refers to a Service Provider and their data.
Subaccounts	This refers to a Service Provider's customers, and the customers' data.

The `X-MSYS-SUBACCOUNT` header

To manage a subaccount from the primary account, you can set the X-MSYS-SUBACCOUNT header to a subaccount ID. This will retrieve or modify only that subaccount's data. The exceptions are the Metrics and Message Events APIs which do not use the X-MSYS-SUBACCOUNT header. Instead, you can set the query parameter subaccounts for the same result.

For example, setting X-MSYS-SUBACCOUNT to 123 on a POST request to /api/v1/sending-domains will create a sending domain that belongs to subaccount 123. And similarly setting X-MSYS-SUBACCOUNT to 123 on a GET request to /api/v1/sending-domains, will return sending domains which belong to subaccount 123.

You can also use the header to filter out subaccount data. By default, when you make GET requests, the API returns both the primary account and subaccount data. When you set the X-MSYS-SUBACCOUNT header to 0, it will return only the primary account data.

When making POST, PUT, or DELETE requests without the X-MSYS-SUBACCOUNT header, only primary account is affected by default, so setting the header to 0 makes no difference. The exception here is webhooks. They act like GET requests, where if you omit the header, they will be sent both the primary account and subaccount data, but if you set the X-MSYS-SUBACCOUNT header to 0, they will only receive the primary account data.

X-MSYS-SUBACCOUNT is not required, but if provided, must be a number.

Pagination

The Subaccounts API supports pagination for queries with larger result sets. Pagination is done through the use of the cursor and per_page query parameters. The per_page query parameter sets the number of subaccounts to return in a single request, and supports a maximum value of 100.

Once you have the response, you then can use links to retrieve the URL for your next page, which will be prefilled with the appropriate value for the cursor query parameter, as well as any other filters you supplied with the original request.

If your result set is less than one page of data, then the links object will not have a next key.

Example

{
  "results": [
    {
      "id": 1,
      "name": "Joe's Garage",
      "status": "active",
      "ip_pool": "my_ip_pool",
      "compliance_status": "active",
      "options": {
        "deliverability": true
      }
    },
    {
      "id": 2,
      "name": "SharkPost",
      "status": "active",
      "compliance_status": "active",
      "options": {
        "deliverability": true
      }
    },
    {
      "id": 3,
      "name": "Dev Avocado",
      "status": "suspended",
      "compliance_status": "active",
      "options": {
        "deliverability": true
      }
    }
  ],
  "total_count": 350,
  "links": {
    "next": "/api/v1/subaccounts?cursor=WzIxMCwyMTBd&per_page=3&sort_by=id"
  }
}

Paginated Response

results array

A page of subaccount objects that match the search parameters.

total_count number

The total number of subaccounts that match the search parameters.

links object

Subaccount object

Example

{
    "results": {
        "id": 123,
        "name": "Joes Garage",
        "status": "active",
        "compliance_status": "active",
        "ip_pool": "assigned_ip_pool",
        "options" {
            "deliverability": false
        }
    }
}

Attributes

id number

Unique ID for the subaccount.

name string

Subaccount display name.
Max length: 64 characters

status enum

Status of the subaccount. Learn about the affects of each status in our subaccount guide.

Possible Values: active, suspended, terminated

compliance_status string

Compliance status of the subaccount.

ip_pool string

The ID of an IP Pool in which to restrict this subaccount's mail deliveries. If the supplied ip_pool is a empty or not present, this subaccount may use any of the account's IP Pools.
Enterprise customers: please consult with your TAM on IP management.

options object

Request

POST /api/v1/subaccounts

{
  "name": "Sparkle Ponies",
  "key_label": "API Key for Sparkle Ponies Subaccount",
  "key_grants": [
    "smtp/inject",
    "sending_domains/manage",
    "message_events/view",
    "suppression_lists/manage",
    "tracking_domains/view",
    "tracking_domains/manage",
    "webhooks/modify",
    "webhooks/view"
  ],
  "key_valid_ips": [],
  "ip_pool": "",
  "options": {
    "deliverability": true
  }
}

Response

{
  "results": {
    "subaccount_id": 888,
    "key": "cf806c8c472562ab98ad5acac1d1b06cbd1fb438",
    "label": "API Key for Sparkle Ponies Subaccount",
    "short_key": "cf80"
  }
}

{
  "errors": [
    {
      "message": "`name` is a required field",
      "param": "name",
      "value": null
    },
    {
      "message": "`key_label` is a required field",
      "param": "key_label",
      "value": null
    },
    {
      "message": "`key_grants` is a required field",
      "param": "key_grants",
      "value": null
    },
    {
      "message": "Invalid `key_grants value`. Supported values are: 'smtp/inject', 'sending_domains/manage', 'message_events/view', 'suppression_lists/manage'",
      "param": "key_grants",
      "value": null
    },
    {
      "message": "`key_valid_ips` must be an Array",
      "param": "key_valid_ips",
      "value": null
    },
    {
      "message": "`key_valid_ips` must have valid netmask values",
      "param": "key_valid_ips",
      "value": null
    },
    {
      "message": "ip_pool must be 20 characters or less",
      "param": "ip_pool",
      "value": "an_ip_pool_name_that_is_too_long"
    },
    {
      "message": "ip_pool must be alphanumeric and underscore",
      "param": "ip_pool",
      "value": "$invalid chars"
    }
  ]
}

Create a Subaccount

POST/api/v1/subaccounts

Creates a new subaccount and an initial subaccount API key. Subaccount API keys are only allowed very specific grants.

Subaccounts are allowed to send mail using the SMTP protocol or Transmissions API, retrieve sending statistics via the Message Events API, manage their Sending Domains, manage their Suppression List, and manage their Templates.

Request Body

name string required

Subaccount display name.
Max length: 64 characters

ip_pool string

setup_api_key boolean, default is true

Whether or not to create an API key for the subaccount. An API key can be created a later time.

key_label string

User friendly identifier for the initial subaccount api key. Required if setup_api_key is true.

key_grants array of strings

List of grants to give to the initial subaccount api key. Required if setup_api_key is true.

Valid values are: smtp/inject, sending_domains/manage, tracking_domains/view, tracking_domains/manage, message_events/view, suppression_lists/manage, transmissions/view, transmissions/modify, webhooks/view, webhooks/modify

key_valid_ips array

List of IP's that the initial subaccount API key can be used from. If not supplied, the API key will be usable from any IP address.

options object

subaccount-level options.

Returns the subaccount's ID, along with the API key and API key label, if one was created.

Stored recipients lists and stored templates are currently not supported for subaccounts sending mail using the Transmissions API.

Request

GET /api/v1/subaccounts/123

Response

{
  "results": {
    "id": 123,
    "name": "Joes Garage",
    "status": "active",
    "compliance_status": "active",
    "ip_pool": "assigned_ip_pool",
    "options": {
      "deliverability": false
    }
  }
}

Retrieve a Subaccount

GET/api/v1/subaccounts/{id}

Parameters

id integer required

This endpoint only returns information about the subaccount, not the resources associated with it.

Request

PUT /api/v1/subaccounts/123

{
  "name": "Hey Joe! Garage and Parts",
  "status": "suspended",
  "ip_pool": ""
}

Response

{
  "results": {
    "message": "Successfully updated subaccount information"
  }
}

{
  "errors": [
    {
      "message": "ip_pool must be 20 characters or less",
      "param": "ip_pool",
      "value": "an_ip_pool_name_that_is_too_long"
    }
  ]
}

Request

PUT /api/v1/subaccounts/123

{
  "options": {
    "deliverability": true
  }
}

Response

{
  "results": {
    "message": "Successfully updated subaccount information"
  }
}

Update a subaccount

PUT/api/v1/subaccounts/{id}

Parameters

id integer required

Request Body

name string

Subaccount display name.
Max length: 64 characters

status enum

Status of the subaccount. Learn about the affects of each status in our subaccount guide.

Possible Values: active, suspended, terminated

ip_pool string

The ID of an IP Pool in which to restrict this subaccount's mail deliveries. To unassign the current IP Pool, provide an empty string.
Enterprise customers: please consult with your TAM on IP management.

options object

subaccount-level options.

Request

GET /api/v1/subaccounts

Response

{
  "results": [
    {
      "id": 123,
      "name": "Joe's Garage",
      "status": "active",
      "ip_pool": "my_ip_pool",
      "compliance_status": "active",
      "options": {
        "deliverability": true
      }
    },
    {
      "id": 456,
      "name": "SharkPost",
      "status": "active",
      "compliance_status": "active",
      "options": {
        "deliverability": true
      }
    },
    {
      "id": 789,
      "name": "Dev Avocado",
      "status": "suspended",
      "compliance_status": "active",
      "options": {
        "deliverability": true
      }
    }
  ]
}

List Subaccounts

GET/api/v1/subaccounts

Parameters

option string

Filters subaccounts to those with the option enabled.

Possible Values: deliverability

cursor string

A cursor provided in the links object of a page of results, used to get the next page of results. Set this parameter to initial to retrieve the first page of results. Passing this parameter will cause results to be paginated.

per_page number, default is 25

Limits the number of subaccounts that are returned in the results object. The maximum allowed value is 100. Passing this parameter will cause results to be paginated.

sort_by string, default is created_at

Sorts results by the specified property. Passing this parameter will cause results to be paginated.

Possible Values: created_at, updated_at, id, name

order string, default is desc

Returns subaccounts in the specified order based on the sort_by parameter. asc returns results in ascending order, desc returns results in descending order. Passing this parameter will cause results to be paginated.

Possible Values: asc, desc

ip_pool string

Returns only subaccounts that are assigned to the IP pool with the ID passed in this parameter. Passing this parameter will cause results to be paginated.

status string

Returns only subaccounts with the specified status. Passing this parameter will cause results to be paginated.

Possible Values: active, suspended, terminated

name string

Returns subaccounts whose name includes the string passed in the parameter. May return false positives. Passing this parameter will cause results to be paginated.

ids string

Returns only subaccounts with the IDs included in the comma separated list in the parameter. Passing this parameter will cause results to be paginated.

Returns a list of your subaccounts. Passing certain query parameters will cause results to be paginated.

Request

GET /api/v1/subaccounts/summary

Response

{
  "results": {
    "total": 46
  }
}

Retrieve Subaccounts Summary

GET/api/v1/subaccounts/summary

Returns the total number of subaccounts.