Manage Different Users with Subaccounts

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.

• A Mailchimp Transactional account

• Your API key

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:

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.

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:

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

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:

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

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.

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

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…

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:

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.

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:

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.

• Subaccounts documentation

• Send Your First Transactional Email

• Reputation and Rejections