Manage Email Across 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 Transactional Email account.  

You might 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 web interface or via the transactional API; in this guide, we’ll focus on the API. 

Let’s say we run a multi-tenant project management application that includes a transactional email element. We’ve been using Mailchimp Transactional Email, 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 user registers for a free account, we create a new subaccount with a somewhat low sending 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

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 Email, 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

Make sure you enter the subaccount name correctly — if you try to send an email from a subaccount that doesn’t exist via the API, it will fail with an error, but if you do so 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 emails 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 Transactional Email account. You can view subaccount activity there in two ways.

To see a high-level overview, including a chart of the subaccounts activity:

  1. Navigate to the Outbound Activity page

  2. Click the Show All Options toggle in the search panel and choose your subaccount from the Subaccounts dropdown

If you’d rather get a lower-level overview where you can also change account status, add notes, and see stats that aren’t available on the Outbound Activity view:

  1. Navigate to the Subaccounts page

  2. Click on the subaccount ID or the View Details button

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

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