Subaccounts

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


Master 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 master 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 master account and subaccount data. When you set the X-MSYS-SUBACCOUNT header to 0, it will return only the master account data.

When making POST, PUT, or DELETE requests without the X-MSYS-SUBACCOUNT header, only master 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 master account and subaccount data, but if you set the X-MSYS-SUBACCOUNT header to 0, they will only receive the master account data.

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

Subaccount object

Example

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

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.

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": ""
}

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.

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"
  }
}

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"
    }
  ]
}

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.

Request

GET /api/v1/subaccounts

Response

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

List all Subaccounts

GET/api/v1/subaccounts

Returns a list of your subaccounts.

Request

GET /api/v1/subaccounts/summary

Response

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

Retrieve Subaccounts Summary

GET/api/v1/subaccounts/summary

Returns the total number of subaccounts.