Multi-tenant applications
If your product has customers who each send their own mail, read this before designing around an assumption that does not hold.
The two shapes, and how to choose
One workspace, your tenancy in your application. You hold one set of keys, you attach your own tenant id to every send, and you enforce isolation in your code.
| Good | Bad |
|---|---|
| one integration, one set of credentials | a bug in your code can send as the wrong customer |
| one reputation to manage | one customer’s bounce rate throttles everyone |
| simple billing | per-customer usage is yours to compute |
A workspace per customer. They sign up, they hold their own keys, you integrate against whichever workspace the request belongs to.
| Good | Bad |
|---|---|
| real isolation, enforced by us | you are managing N sets of credentials |
| their reputation is theirs alone | onboarding is a signup, not an API call |
| their billing is theirs | no API to create a workspace, so it is manual |
Most products want the first and should know what they are accepting. The second is right when your customers are large enough that one of them damaging the others is unacceptable.
If you take one workspace, do these
Put your tenant id in a custom header on the message. It will not help you query, but it is in the stored message and in the bounce you investigate six weeks later.
Use one sending domain per customer where you can. Domain reputation is per domain, so this is the one isolation the platform genuinely gives you for free: a customer with a bad list damages their own domain rather than the shared one. It requires each to verify a domain, which is friction worth paying for.
Suppress per your tenant, not only per workspace. Our suppression list is workspace-wide, so an address suppressed by one of your customers is suppressed for all of them. That is usually right for complaints and wrong for unsubscribes, which are a relationship with one of your customers rather than with you. If that distinction matters, keep your own list and filter before you send.
Compute usage yourself. GET /v1/usage is the workspace total. Nothing
attributes it to your customers.
The reputation consequence, stated plainly
On one workspace, bounce rate is pooled. One customer uploading a bought list
can move the whole workspace to throttled, which lowers the rate cap for
every other customer you have.
Nothing on the platform protects you from that. The defences are yours:
validate addresses at signup, cap new customers until they have a history,
and watch GET /v1/reputation as an operational
metric rather than a curiosity.
Keys and scopes
One key per deployment, not one per customer, because the per-customer key does not exist. Scope it to what that service does, label it for where it runs, and rotate on exposure.
If you are tempted to issue a key to a customer so they can send directly: that key can send as every other customer too. See Permissions and least privilege.