> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailchannels.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-tenancy overview

> Understand the two isolation mechanisms available in Email API, and when to use each.

Email API provides two levels of isolation for separating email traffic: **sub-accounts** and **sender IDs**. They operate
at different layers and can be used independently or together.

|                           | Sub-account | Sender ID |
| ------------------------- | ----------- | --------- |
| Separate API keys         | Yes         | No        |
| Separate sending limits   | Yes         | No        |
| Separate suppression list | Yes         | No        |
| Separate webhooks         | Yes         | No        |
| Separate usage reporting  | Yes         | No        |
| Can be suspended          | Yes         | No        |
| Reputation isolation      | Yes         | Yes       |

## Sub-accounts

### What are sub-accounts?

Sub-accounts allow you to create and manage many distinct sending identities under your main account. This feature
is useful for agencies, resellers, or organizations that need to manage email sending for multiple clients or departments
while maintaining clear separation between them. Each sub-account has its own credentials, sending controls, suppression list,
webhook configuration, and usage reporting.

### When to use sub-accounts

Sub-accounts are useful when you need separate credentials, limits, or operational controls.

| Use case                                                     | Why use a sub-account                                                             |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| Agency or reseller sending for multiple clients              | Keep each client isolated with its own credentials and usage.                     |
| Multi-tenant SaaS application                                | Limit the impact of one tenant's sending behavior on other tenants.               |
| Separate business units or brands                            | Give each group independent API keys, SMTP passwords, webhooks, and suppressions. |
| Migration from providers with subusers, servers, or projects | Preserve existing tenancy boundaries while moving to MailChannels.                |

### When not to use sub-accounts

Do not create a sub-account just to send from another domain. If the same application and team own the traffic, Domain
Lockdown, SPF, DKIM, and DMARC may be enough.

Every sub-account adds another operational boundary. Each one comes with separate credentials, suppressions,
webhooks, usage reporting, and limits. Those boundaries are helpful when different clients, tenants, teams, or
applications need to be managed independently. They add unnecessary overhead when the only difference is the domain in
the `from.email` address.

For example, a SaaS product might send billing mail from `billing.example.com`, product alerts from
`notifications.example.com`, and support updates from `support.example.com`. If the same engineering team owns all three
streams and they share the same operational process, create the required Domain Lockdown records and authentication
records for each domain instead of creating three sub-accounts. Use sub-accounts only when you need a separate owner,
credential set, suppression policy, webhook endpoint, usage limit, or incident response path.

### Sub-accounts and suppression lists

Each sub-account has its own suppression list, separate from the parent account's. A recipient on the parent
account's list is not blocked from receiving mail from a sub-account unless they are also on that sub-account's list.

To read or write a sub-account's suppression list, authenticate the request with the **sub-account's own API key** —
not the parent's. See the [suppression list documentation](/email-api/suppression-api-actions) for the available endpoints.

### Sub-accounts and delivery events

Each sub-account manages its own delivery-event webhook, separate from the parent account's. Events from a
sub-account's messages are delivered only to that sub-account's webhook; the parent account does not receive a copy.

To enroll, list, validate, or remove a sub-account's webhook, authenticate the request with the **sub-account's own
API key**, not the parent's. See the [webhooks documentation](/email-api/webhooks) for the available endpoints
and event schema.

## Sender IDs

### What is a sender ID?

A sender ID is a label that Email API assigns to each outbound message based on characteristics found in the message
headers. It acts as a **reputation boundary**: messages sharing the same sender ID are grouped together for delivery
reputation tracking, so poor sending behavior from one traffic stream does not automatically affect others.

Sender IDs are scoped to the account or sub-account that sends the message. If two sub-accounts happen to derive the
same sender ID value from their message headers, those values remain separate because they are always qualified by the
sub-account they belong to.

### What sender IDs provide

Sender IDs give you reputation isolation within a single set of credentials. You can separate the sending reputation of
distinct traffic streams, without creating a new sub-account for each stream.

Unlike sub-accounts, sender IDs do not provide separate API keys, sending limits, suppression lists, webhooks, or usage
reporting. They are a lighter-weight boundary suited to cases where operational separation is not required but reputation
isolation is still useful.

### When to use sender IDs

| Use case                                                         | Why use a sender ID                                                                            |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Separating transactional and promotional mail within one account | Protect transactional reputation from promotional sending risk, without splitting credentials. |
| Distinguishing mail streams within a sub-account                 | Identify and isolate a specific integration, product, or campaign at the reputation level.     |
| Tracking reputation per sending use case for a single tenant     | Get per-stream visibility without the overhead of managing multiple sub-accounts.              |

## Choosing the right boundary

Use this guide to help decide which mechanism to use.

**Use a sub-account when:**

* Different customers, tenants, or teams need their own API keys or SMTP credentials.
* You need to enforce separate sending quotas or limits.
* Each sender needs its own suppression list and webhook endpoint.
* You need to be able to suspend or resume a tenant's sending independently.

**Use a sender ID when:**

* A single account or sub-account sends meaningfully different streams of mail, for example, transactional and promotional,
  and you want to isolate their reputations.
* You want per-stream reputation tracking without the overhead of managing separate credentials, limits, and webhooks.