Overview (Bulk / Marketing)

The bulk (marketing) module is independent from the transactional module. It uses the same authentication — Authorization: Bearer $MAILERDASH_API_KEY — but operates on a different channel (X-Md-Channel: bulk). You do not need to add that header to your REST calls: the bulk-worker adds it automatically when dispatching campaigns. Your interaction with the API is always to manage data (contacts, lists, templates, campaigns, sequences), not to trigger sends directly.

Data model

The general flow is:

Contacts → added to Lists → Campaigns (or Sequences) point to a List + a Template → the bulk-worker dispatches the sends.

Resources

Contacts

Individual records with email, name, and arbitrary metadata. Each contact has a status that reflects their deliverability state:

• active — can receive emails.
• unsubscribed — unsubscribed; will not receive further messages.
• bounced — a permanent bounce (5.x.x) occurred; excluded from future sends.
• complained — marked an email as spam via FBL; excluded from future sends.

Contacts are the source of truth for your subscribers.

Lists

Groups of contacts. A campaign points to exactly one list. You can have separate lists per product, segment, or channel (newsletter, onboarding, reactivation). Contacts can belong to multiple lists.

Templates

Reusable HTML and/or plain-text content, with its own subject. Campaigns and sequences reference them by ID, letting you update the content without modifying already-configured campaigns.

Campaigns

One-shot bulk send to a list. Lifecycle:

• draft — draft state, editable.
• send — queued for immediate dispatch.
• sent — the bulk-worker finished processing all contacts.

Once sent, a campaign is not modifiable.

Sequences

Drip automations. A sequence defines steps (steps) with a delay between each one (hours or days), and has subscribers — contacts that advance through the steps at the configured intervals. Useful for automated onboarding, nurturing, and follow-ups.

Suppressions

All bulk routes respect the account’s global suppression list. Contacts with status bounced, complained, or unsubscribed are automatically skipped at send time — you don’t need to filter them manually.

See the suppressions guide to learn how to manage the list and what happens when a contact is suppressed from different sources.

Bounces and complaints update the contact's status

When the system processes a permanent bounce or an FBL complaint, the associated contact automatically changes to bounced or complained. From that point on they are excluded from all future sends, across every list and campaign, without any manual intervention needed.

Guides by resource

Resource	Guide
Contacts	Create, import, and manage contacts
Lists	Organize contacts into lists
Templates	Create reusable templates
Campaigns	Send bulk campaigns
Sequences	Automate with sequences (drip)