Mailchimp Developer Homepage

Manage Different Users with Subaccounts

At a glance

If you send emails on behalf of different clients or if you run multi-tenant systems to separate sending for different users, you can use subaccounts to manage reputation, activity, reports, and quotas across different senders under a single Mailchimp Transactional account.  

You could use subaccounts in your application for a variety of reasons:

  • A tech agency offering transactional email to its clients wants to pay for one account but get separate API keys for each client

  • A multi-tenant application wants to allow customers to customize the emails it sends on their behalf

  • A large organization wants to segment usage by departments internally for better accounting

You can create and manage subaccounts in the app or via the Transactional API. In this guide, we’ll focus on the API; for details about managing subaccounts in the app, see the subaccounts docs.

Let’s say we run a multi-tenant project management application that includes a transactional email element. We’ve been using Mailchimp Transactional, but it’s been difficult to keep track of how many emails our individual users are sending, or to limit them to different quotas. 

We’ve decided to start using subaccounts, which will give us the granularity we need to handle these different client needs, and we’re going to implement subaccounts with our newest customer—Acme Widgets. We’ll add a subaccount for Acme, start sending emails, view their stats, and, when we (amicably!) part ways, eventually delete their subaccount.

What you’ll need

Create a subaccount

Acme Widgets has registered for a new free account in our app, so let’s get started.

When a new client registers for a free account, we create a new subaccount. By default, subaccounts have their own hourly quotas that match that of the main account, but you can also set a custom hourly quota—any amount lower than the main hourly quota.

We’re starting Acme Widgets at a low custom hourly quota: 10 emails per hour. (Gotta incentivize premium signups somehow!) To do this via the API, our code might look like:

Create a subaccount

curl -X POST \
  https://mandrillapp.com/api/1.0/subaccounts/add \
  --data-binary @- << EOF 
{
  "key": "YOUR_API_KEY",
  "id": "UNIQUE_ACCOUNT_ID",
  "name": "Acme Widgets",
  "notes": "Free tier",
  "custom_quota": 10
}
EOF

You can also get started directly in the Mailchimp Transactional app: see the docs for instructions on setting up a new subaccount and modifying its hourly quota.

Send email from a subaccount

Now that our new subaccount is up and running, we’re ready to start sending email on behalf of Acme Widgets. You can either use the subaccount option in the API (see the relevant endpoint here) or you can use the X-MC-Subaccount header if you’re sending via SMTP. Again, we’ll focus on the API.

Since we’ve already been sending messages with Mailchimp Transactional, updating our code to send from a subaccount is simple—just add a subaccount key along with your request:

Send email from a subaccount

curl -X POST \
  https://mandrillapp.com/api/1.0/messages/send \
  --data-binary @- << EOF 
{
  "key": "YOUR_API_KEY",
   "message": {
     "text": "This email was sent from a subaccount!",
      "subject": "Subaccount test",
      "from_email": "hello@example.com",
      "to": [{ 
        "email": "freddie@example.com",
        "type": "to" 
      }],
      "subaccount": "UNIQUE_ACCOUNT_ID"
    }
}
EOF

Note: Make sure you enter the subaccount name correctly. If you try to send an email via the API from a subaccount that doesn’t exist, it will fail with an error. However, if you try to send from a nonexistent subaccount via SMTP, the email will be accepted by the SMTP server but will ultimately fail to send.

View subaccount activity

We’ve been sending transactional email for Acme Widgets for a while now, and it’s time to check out our subaccount’s activity, which Mailchimp automatically tracks. 

The easiest way to do so is directly in your Mailchimp Transactional account. But if you need programmatic access to account activity—for example, if you needed to set up your own dashboard or jobs to track subaccount activity—you can fetch it from the API like so:

View subaccount activity

curl -X POST \
  https://mandrillapp.com/api/1.0/subaccounts/info \
  --data-binary @- << EOF 
{
  "key": "YOUR_API_KEY",
  "id": "UNIQUE_ACCOUNT_ID"
}
EOF

Update a subaccount’s quota

Acme Widgets has found our application invaluable—but they’re bumping up against the limitations on our free tier, so they’ve decided to upgrade to a premium account. As part of the upgrade, we’ll increase their subaccount’s hourly email quota to 100 emails per hour.

Update a subaccount’s quota

curl -X POST \
  https://mandrillapp.com/api/1.0/subaccounts/update \
  --data-binary @- << EOF 
{
  "key": "YOUR_API_KEY",
  "id": "UNIQUE_ACCOUNT_ID",
  "custom_quota": 100
}
EOF

Pause and resume sending from a subaccount

Uh oh. Acme Widgets is three months late on their subscription fees. We’re hoping to resolve this soon, so rather than deleting their subaccount, we’ll pause sending from their subaccount and resume once they’ve paid.

To pause sending…

Pause sending from a subaccount

curl -X POST \
  https://mandrillapp.com/api/1.0/subaccounts/pause \
  --data-binary @- << EOF 
{
  "key": "YOUR_API_KEY",
  "id": "UNIQUE_ACCOUNT_ID"
}
EOF

But wait, good news—Acme Widgets has found their credit card! 

Let’s resume sending from their account:

Resume sending from a paused subaccount

curl -X POST \
  https://mandrillapp.com/api/1.0/subaccounts/resume \
  --data-binary @- << EOF 
{
  "key": "YOUR_API_KEY",
  "id": "UNIQUE_ACCOUNT_ID"
}
EOF

You can also pause and resume sending directly in the Mailchimp Transactional app.

Delete a subaccount

Oh no. Acme Widgets shipped a bug to production, causing a massive site outage during their most active quarter of the year. Despite the best efforts of our sales team, Acme Widgets has decided to cancel their account.

As part of that cancellation, we’ll need to delete their subaccount. Here’s how:

Delete a subaccount

curl -X POST \
  https://mandrillapp.com/api/1.0/subaccounts/delete \
  --data-binary @- << EOF 
{
  "key": "YOUR_API_KEY",
  "id": "UNIQUE_ACCOUNT_ID"
}
EOF

You can also delete a subaccount directly in the Mailchimp Transactional app. Keep in mind that deleting a subaccount is permanent, and Mailchimp cannot recover a subaccount after it is deleted.