Overview

Mailgun provides the ability for a primary account to create and manage their own subaccounts. 

• Primary Account - the top-level organizational Mailgun account from where subaccounts originate
• Subaccount - the separate-but-linked accounts 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. Click the Create subaccount button.

   

5. On this new page, enter the name for your subaccount and click the Create button. Prior to doing so, you may check the option to delegate a single IP pool to this subaccount.

   

6. You can also configure the subaccount's feature access as desired and click the Save button. (See more details in the section, Managing features for a Subaccount)

   

7. If successful, you'll see the new subaccount details listed below as part of the Edit subaccount page.

   

8. Click either the Back hyperlink or the Back to subaccounts button to return to the subaccounts page, which will list all created subaccounts.

   

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 metadata for Subaccounts

Present on the Subaccounts page are the following details about each subaccount: 

• name
• status (enabled, closed, or disabled)
• last send (30 days maximum date range; the number of days we can show is limited to the retention period for the parent account, which is a maximum of 30 days)
• number of dedicated IPs
• number of IP pools
• number of domains
• number of API keys
• number of users
• created date
• last modified date

At the end of each row there is an ellipsis (three horizontal dots) icon that, upon clicked, will display a list of actions that can be performed upon the chosen subdomain

Note: If you're looking for the email sending analytics and details for a subaccount, a link to the Reporting section is provided in the banner of the page.

Logging into a Subaccount

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

2. Select the Login to subaccount option and choose one of the page suboptions, which will log you directly into the indicated page on the subaccount (as long as your account user's role has the necessary RBAC permissions).

   

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

Disabling a subaccount stops all current and prevents all future functionality on the subaccount until it is reenabled. We'll show you how to accomplish this below:

1. Click the ellipsis (three horizontal dots) 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 ellipsis (three horizontal dots) icon to view the available options.
    

   

2. Select the Enable subaccount 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 ellipsis (three horizontal dots) icon to view the available options.
    

   

2. Select the Edit subaccount option.

   • Note: The Edit subaccount option appears only to users with Admin, Developer, or Billing 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. Within the Account details section of the resulting page, change the name for your subaccount and/or the IP Pool assigned. When finished, click the Update button.

   

4. While here, you can also manage access to features for a subaccount, if desired. We'll cover that in the next section

Managing feature access 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:

• Sending
  • You can disable sending completely for any subaccount.
  • For any subaccount allowed to send, you may choose to limit its monthly sending.
  • Note: Subaccounts will be able to see their configured message limit, and how many messages they've already sent in relation to that limit. However, subaccounts cannot modify the message limit; only the primary account can perform this action.
  • Note: If you’re looking for information on configuring custom message limits on your account (and you don’t use subdomains) or on your primary/main account (and you do use subdomains), please see this article.
• Email Previews
• Inbox Placement Testing
• Validations
  • Single Validations
  • Bulk Validations

Aside from assigning these features on the Create subaccount page, you can also adjust them at any time after subaccount creation by going to the Edit subaccount page, which we'll demonstrate below:

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

   

2. Select the Edit subaccount option.
   • Note: The Edit subaccount option appears only to users with Admin, Developer, or Billing 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. Within the Feature access section of the resulting Edit subaccount page, toggle the features you would like to enable or disable for your subaccount and then click the Save button.

   

Note: Managing of features is also available by using the Subaccount Features endpoint.

Deleting a Subaccount

1. Click the ellipsis (three horizontal dots) 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. Be sure to utilize the filter if desired to view specific subaccounts.

   

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!