Overview

Mailgun provides 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. 

Note: 
The Mailgun Subaccounts feature is currently available for Enterprise customers only.

Creating a Subaccount

If you have access to our Subaccounts feature, you can add subaccounts through the following steps.

1. First, log in to the Mailgun Control Panel (if you have not already done so).
2. Then, at the top-right corner of the page, click the Profile drop-down menu to expand its list of options.
3. Next, click the Subaccounts option. Alternatively, you can use this direct link.
    

4. 

5. Click the Create Subaccount button.
    

   

6. Finally, within the modal that appears, enter the name for your subaccount and click the Create button.
    

   

7. 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.

1. First, log in to the Mailgun Control Panel (if you have not already done so).
2. Then, at the top-right corner of the page, click the Profile drop-down menu to expand its list of options.
3. 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

1. Click the gear icon to view the available options.
    

   

2. Select the Login to Subaccount option.
    

   

3. 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

1. Click the gear icon to view the available options.
    

   

2. Select the Disable option.
    

   

3. If successful, the subaccount will have a status of Disabled similarly to the image below.
    

   

Enabling a Subaccount

1. Click the gear icon to view the available options.
    

   

2. Select the Enable option.
    

   

3. If successful, the subaccount will have a status of Enabled similarly to the image below.
    

   

Editing details for a Subaccount

1. Click the gear icon to view the available options.
    

   

2. Select the Edit Details option.
    

   

3. Finally, within the modal that appears, change the name for your subaccount and click the Update button.
    

   

Managing features for a Subaccount

Account features for subaccounts are managed through our Subaccounts API (specifically the features endpoint). Currently, the following features can be enabled/disabled per subaccount:

• Email Previews
• Inbox Placement Testing
• Validations (single)
• Validations (bulk)

1. Click the ellipsis (three horiztonal dots) icon to view the available options.

   

2. Select the Manage Features option.
   • Note: The Manage Features option appears only to users with Admin or Developer roles on the parent (main/primary) account. Users of other roles on the parent account, as well as all users of any role on the subaccount, will not see this option listed.

3. Finally, within the modal that appears, toggle the features you would like to enable or disable for your subaccount click the Save button.

   

Deleting a Subaccount

1. Click the gear icon to view the available options.
    

   

2. Select the Delete option.
    

   

Viewing usage reports

We provide a way to view various usage metrics for all of your subaccounts. The reports will expose the following metrics if there is any usage data for those particular metrics:  

• Email Messages (using Processed total)
• Email Validations (using Validations total)
• Inbox Placement (using Seed Test total)
• Email Preview (Email preview total - email preview failed total) 

Aggregated totals will be provided with usage stats refreshed every 24 hours.

To view this information on your account, please proceed through the following steps.

1. First, log in to the Mailgun Control Panel (if you have not already done so).
2. Then, at the top-right corner of the page, click the Profile drop-down menu to expand its list of options.
3. Next, click the Usages option. Alternatively, you can use this direct link.

   

4. Now, view the data as segmented by each subaccount as well as the aggregate metric totals for all subaccounts.

5. 

Further, by clicking the ellipsis icon in the action column for a given subaccount, you can disable the subaccount, if needed. Disabling a subaccount stops all current and prevents all future functionality on the subaccount until it is reenabled. 

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.

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.

Need Support?

Our Support Team here at Sinch Mailgun is happy to help! Reach out to us in the Support page of your Mailgun Control Panel, and we'll be with you shortly!