Subaccounts
Table of Contents
Summary of Subbacount Features
Performing API requests "on behalf of" Subaccounts
Mailgun’s subaccount functionality allows account admins the ability to create and manage a new Mailgun account that is linked to the primary account, but with wholly separate assets such as sending domains, IPs, API keys, and if necessary, users.
From a billing and administrative standpoint, all usage on the subaccount level is tracked and rolled into the usage of the primary account. At this time subaccounts cannot be billed separately.
Note:
- Subaccount access is based on plan features. To see available plans visit https://www.mailgun.com/pricing/
- At this time Mailgun Optimize is not available on subaccounts
Terminology
| Term | Definition |
|---|---|
| Primary Account | The top-level organizational Mailgun account where subaccounts originate. |
| Subaccount | The separate-but-linked entities used to organize various use-cases, customers, etc. |
| RBAC Permissions | Primary account admin users can create/manage subaccounts. Primary account RBAC user types with access to reporting and logs can view subaccount data. |
Name and Status
Additionally primary account admins can edit name and status of subaccounts:
| Subaccount Status | Description |
|---|---|
| Enabled | Default, subaccount has all available access via API and UI. |
| Disabled | API access suspended, UI access limited to read-only state. |
| Closed | Subaccount is deleted all data specific to that subaccount including API keys users and sending domains and sending history/stats are removed and cannot be recovered. |
Use Cases
As subaccounts are designed for full segmentation of account assets, they can be used to support a number of business cases. The most common would be the need to give a separate business unit, project, or even a customer separate access to Mailgun including the separate of sending assets and data/reporting.
Other potential use cases include:
- You are a marketing platform that needs to segment your end-users into their own separate subaccounts.
- A cross-functional team also needs email capabilities but you need to ensure their sending assets and data is separate from your own.
- You have a specific mail stream or project that needs separate assets and reporting.
Summary of Subbacount Features
As the primary account, you will have the ability to:
- Create and manage access of individual subaccounts including API keys, sending domains, and users specific to subaccount
- View/create reporting filtered on or grouped by your subaccounts
- View event data/logs filtered by subaccount
- Create/manage assign dedicated IP pools to subaccounts including setting the sending IP pool at send time
As a subaccount user, you will have the ability to:
- send messages via API (using subaccount level API key)
- send messages via SMTP
- set sending domains
- set webhooks
- view sending statistics via UI and API
- view event logs via UI and API
- create/edit templates via UI and API
Note:
Subaccount API keys have no restrictions and can be used on all available endpoints at the subaccount level.
Subaccounts and IP Pools
As a primary account you can manage the IP Pools that will be used by your subaccounts in one of two ways.
-
Define IP pool at send time - the primary account can use the header
X-Mailgun-Sending-Ip-Pooland the pool ID of the IP pool contained on the primary account. - Delegate IP Pool to subaccount - during either the creation or later editing the details of the subaccount from the primary account UI, an admin can define a single IP pool for use by the subaccount. The IP pool can then be assigned to any sending domain contained on the subaccount.
Performing API requests "on behalf of" Subaccounts
Primary accounts can make API calls on behalf of their subaccounts, e.g. sending messages, managing mailing lists, etc. This is accomplished by using the X-Mailgun-On-Behalf-Of header, which must contain the subaccount’s account ID.
Note:
Moreover, this header is a request header, not a message header. As such, this is not the h:header_value construct used for adding Reply-To fields, for instance. How to add request headers differs with each language; nonetheless, the below example shows how to add a request header in cURL.
Important Note:
If the X-Mailgun-On-Behalf-Of header is NOT included, the action could occur on the primary account rather than the subaccount.
Request Header
X-Mailgun-On-Behalf-Of: SUBACCOUNT_ACCOUNT_IDWhere SUBACCOUNT_ACCOUNT_ID is a value like 646d00a1b32c35364a2ad34f. The header’s data type is a string, and each programming language likely will have the entire header (i.e. the header name and value) enclosed in single- or double-quotes (as shown in the below example).
Example cURL
curl -s --user 'api:PRIMARY_ACCOUNT_API_KEY' \
https://api.mailgun.net/v3/SUBACCOUNT_DOMAIN/messages \
-H "X-Mailgun-On-Behalf-Of: SUBACCOUNT_ACCOUNT_ID" \
-F from='Excited User <YOU@SUBACCOUNT_DOMAIN>' \
-F to='foo@example.com' \
-F subject='Hello' \
--form-string html='<html>HTML version of the body</html>'As you'll notice in the above example, the API key used is that of the primary account whereas the domain and account ID used is that of the subaccount.
