Table Of Contents
Quick Overview
Creating A Subaccount
Managing Subaccounts
Viewing Top-Level Metrics For Subaccounts
Logging Into A Subaccount
Disabling A Subaccount
Enabling A Subaccount
Editing Details For A Subaccount
Deleting A Subaccount
Performing API Requests "On-Behalf Of" Subaccounts
Got Questions?
Overview
Due to customer feedback, Mailgun has implemented the ability for a primary account to create and manage their own subaccounts.
- 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.
In this article, we'll demonstrate the process of creating a subaccount and managing subaccounts from your primary account.
Creating A Subaccount
If you have access to our Subaccounts feature, you can add subaccounts through the following steps.
- First, log in to the Mailgun Control Panel (if you have not already done so).
- Then, at the top-right corner of the page, click the Profile drop-down menu to expand its list of options.
-
Next, click the Subaccounts option. Alternatively, you can use this direct link.
-
Click the Create Subaccount button.
- Finally, within the modal that appears, enter the name for your subaccount and click the Create button.
- If successful, the new subaccount will be listed similarly to the image below.
Managing Subaccounts
Various reporting metrics and configuration options are available for each subaccount. Most importantly, the ability to login to the subaccount's Mailgun Control Panel is located here. We'll demonstrate below where to find these tools. First though, let's navigate to the Subaccount page of the Mailgun Control Panel.
- First, log in to the Mailgun Control Panel (if you have not already done so).
- Then, at the top-right corner of the page, click the Profile drop-down menu to expand its list of options.
-
Next, click the Subaccounts option. Alternatively, you can use this direct link.
Now that we are located at the Subaccounts page, let's explore the available options.
Viewing Top-Level Metrics For Subaccounts
Present on the Subaccounts page are the number of Accepted, Delivered, Failed, and Bounced events for each subaccount during the current invoicing period.
Logging Into A Subaccount
-
Click the gear icon to view the available options.
-
Select the Login to Subaccount option.
-
Manage the subaccount as needed (the domains, routes, mailing lists, etc.). Imaged below, you'll notice various account options in the subaccount's profile refer specifically to the subaccount such as Subaccount Settings and the ability to logout of the subaccount.
Disabling A Subaccount
-
Click the gear icon to view the available options.
-
Select the Disable option.
- If successful, the subaccount will have a status of Disabled similarly to the image below.
Enabling A Subaccount
-
Click the gear icon to view the available options.
-
Select the Enable option.
- If successful, the subaccount will have a status of Enabled similarly to the image below.
Editing Details For A Subaccount
-
Click the gear icon to view the available options.
-
Select the Edit Details option.
- Finally, within the modal that appears, change the name for your subaccount and click the Update button.
Deleting A Subaccount
-
Click the gear icon to view the available options.
-
Select the Delete option.
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.
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.
Please 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_ID
Where 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.
Got Questions?
Mailgun by Sinch has answers! If you have any concerns or questions, please send us a Support ticket using the Support page within your Mailgun Control Panel. Our Support Team will be happy to assist!