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.
Primary account | This refers to a Service Provider and their data. |
Subaccounts | This refers to a Service Provider's customers, and the customers' data. |
X-MSYS-SUBACCOUNT
headerTo 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.
{
"results": {
"id": 123,
"name": "Joes Garage",
"status": "active",
"compliance_status": "active",
"ip_pool": "assigned_ip_pool",
"options" {
"deliverability": false
}
}
}
Unique ID for the subaccount.
Subaccount display name.
Max length: 64 characters
Status of the subaccount. Learn about the affects of each status in our subaccount guide.
Possible Values: active
, suspended
, terminated
Compliance status of the subaccount.
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.
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": ""
}
{
"results": {
"subaccount_id": 888,
"key": "cf806c8c472562ab98ad5acac1d1b06cbd1fb438",
"label": "API Key for Sparkle Ponies Subaccount",
"short_key": "cf80"
}
}
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.
Subaccount display name.
Max length: 64 characters
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.
true
Whether or not to create an API key for the subaccount. An API key can be created a later time.
User friendly identifier for the initial subaccount api key. Required if setup_api_key
is true.
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
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.
GET /api/v1/subaccounts/123
{
"results": {
"id": 123,
"name": "Joes Garage",
"status": "active",
"compliance_status": "active",
"ip_pool": "assigned_ip_pool",
"options": {
"deliverability": false
}
}
}
This endpoint only returns information about the subaccount, not the resources associated with it.
PUT /api/v1/subaccounts/123
{
"name": "Hey Joe! Garage and Parts",
"status": "suspended",
"ip_pool": ""
}
{
"results": {
"message": "Successfully updated subaccount information"
}
}
PUT /api/v1/subaccounts/123
{
"options": {
"deliverability": true
}
}
{
"results": {
"message": "Successfully updated subaccount information"
}
}
Subaccount display name.
Max length: 64 characters
Status of the subaccount. Learn about the affects of each status in our subaccount guide.
Possible Values: active
, suspended
, terminated
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.
GET /api/v1/subaccounts?option=deliverability
{
"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
}
}
]
}
Filters subaccounts to those with the option enabled. The only valid value is currently deliverability
.
Returns a list of your subaccounts.
GET /api/v1/subaccounts/summary
{
"results": {
"total": 46
}
}
Returns the total number of subaccounts.