Setting up MailBlastr for multi-tenant apps

Many SaaS platforms need to send email on behalf of their tenants — transactional notifications, onboarding sequences, or campaigns from a tenant’s own domain. There are two main ways to configure MailBlastr for this. Neither is universally "right"; the best choice depends on how much control you want and what your tenants need.

At a glance

Option A: a single MailBlastr account

You manage everything from one account: add each tenant’s domain, verify it, and issue a domain-scoped API key so each tenant can only send from their own domain. All sending, billing, and analytics flow through your account. Domain setup is API-driven; issuing the key itself is a dashboard step.

When a tenant signs up, create and verify their domain.

1. Create the tenant's domain:

import { Mailblastr } from 'mailblastr';

const mb = new Mailblastr('mb_xxxxxxxxx');

const { data, error } = await mb.domains.create({ "name": "tenant-domain.com" });
console.log({ data, error });

2. After the tenant publishes the DNS records, trigger verification:

import { Mailblastr } from 'mailblastr';

const mb = new Mailblastr('mb_xxxxxxxxx');

const { data, error } = await mb.domains.verify('DOMAIN_ID');
console.log({ data, error });

Once verified, create a sending_access key scoped to that domain so the tenant can only send from it. This step is dashboard-only — on the API Keys page, create the key, choose Sending access, and restrict it to the tenant’s verified domain. POST /api-keys is not available to API-key callers: it returns 403 dashboard_only for every key, so a tenant key can never mint another tenant a key. See Create an API key.

• Pros: domain setup automates over the API; domain-scoped keys confine each tenant to their own domain; one account to manage.
• Cons: no per-tenant analytics in the dashboard; tenants share your sender reputation; aggregate volume will likely need a quota increase.

Option B: separate accounts (BYOK)

In the Bring-Your-Own-Key model, each tenant creates their own MailBlastr account, adds their domain, and gives you their API key. Your app stores each tenant’s key and uses it when sending for them:

import { Mailblastr } from 'mailblastr';

// Look up the calling tenant's own MailBlastr key, then send with it.
const tenantApiKey = await getTenantKey(tenantId);
const mb = new Mailblastr(tenantApiKey);

await mb.emails.send({
  from: 'notifications@tenant-domain.com',
  to: ['user@example.com'],
  subject: 'Your order has shipped',
  html: '<p>Your order #1234 is on its way.</p>',
});

• Pros: full isolation — each tenant’s reputation and deliverability are independent; no liability for tenant behavior on your account; each tenant has their own dashboard and rate limits.
• Cons: each tenant must create and manage their own account and plan, which adds onboarding friction for those unfamiliar with email infrastructure.

Webhook routing

With Option A, route on the sending domain. Every webhook payload carries data.from, and each tenant sends from their own verified domain — so mapping that domain back to a tenant id resolves every event unambiguously.

With Option B, each tenant configures their own webhooks, so events are naturally isolated — no routing logic needed.

Deliverability & migration

Sender reputation is tied to the sending account and its domains. Under Option A all tenants share one reputation; under Option B each is independent. Either way, every new tenant domain should follow a warm-up schedule and ideally send from a subdomain to protect the tenant’s root domain.

See Create domain and Webhooks for the underlying endpoints, and Create an API key for the dashboard key step.