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.
      SubaccountsFeature.1.png
    4. Click the Create Subaccount button.
      SubaccountsFeature.2.png
    5. Finally, within the modal that appears, enter the name for your subaccount and click the Create button.
      SubaccountsFeature.3.png
    6. 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


    Deleting a Subaccount

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

     

    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.

    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 section of your Mailgun Control Panel, and we'll be with you shortly!