We're experiencing difficulty. Our engineers are on it. Please check status.mailgun.com for real-time updates.

Subaccounts

Article Preview

    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. SubaccountsFeature.1.png
    5. Click the Create Subaccount button.
       
      SubaccountsFeature.2.png
    6. Finally, within the modal that appears, enter the name for your subaccount and click the Create button.
       
      SubaccountsFeature.3.png
    7. If successful, the new subaccount will be listed similarly to the image below.
       
      SubaccountsFeature.4.png

     

    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.
       
      SubaccountsFeature.1.png

    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.
     

    SubaccountsFeature.5.png


    Logging into a Subaccount

    1. Click the gear icon to view the available options.
       
      SubaccountsFeature.5.png
    2. Select the Login to Subaccount option.
       
      SubaccountsFeature.6.png
    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.
       
      SubaccountsFeature.10.png


    Disabling a Subaccount

    1. Click the gear icon to view the available options.
       
      SubaccountsFeature.5.png
    2. Select the Disable option.
       
      SubaccountsFeature.6.png
    3. If successful, the subaccount will have a status of Disabled similarly to the image below.
       
      SubaccountsFeature.8.png


    Enabling a Subaccount

    1. Click the gear icon to view the available options.
       
      SubaccountsFeature.5.png
    2. Select the Enable option.
       
      SubaccountsFeature.9.png
    3. If successful, the subaccount will have a status of Enabled similarly to the image below.
       
      SubaccountsFeature.5.png

     

    Editing details for a Subaccount

    1. Click the gear icon to view the available options.
       
      SubaccountsFeature.5.png
    2. Select the Edit Details option.
       
      SubaccountsFeature.6.png
    3. Finally, within the modal that appears, change the name for your subaccount and click the Update button.
       
      SubaccountsFeature.7.png

     

    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.
      Screenshot 2024-10-30 at 12.31.43 PM.png
    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.
    Screenshot 2024-10-30 at 12.30.01 PM.png
    1. Finally, within the modal that appears, toggle the features you would like to enable or disable for your subaccount click the Save button.
      Screenshot 2024-11-06 at 10.36.19 AM.png

     

    Deleting a Subaccount

    1. Click the gear icon to view the available options.
       
      SubaccountsFeature.5.png
    2. Select the Delete option.
       
      SubaccountsFeature.6.png

     

    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.
      Screenshot 2024-10-30 at 12.39.19 PM.png
    4. Now, view the data as segmented by each subaccount as well as the aggregate metric totals for all subaccounts.
    5. image.png

    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.

    Moreover, this header is a request header, not a message header. As such, this is not the h:header_value construct used for adding head fields like the Reply-To, 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_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!