Skip to main content
Subscription state controls whether a contact can receive emails from MailerPath. Every send checks this state before dispatch — an unsubscribed contact is always skipped, regardless of the send source.

​
The is_subscribed field

Each contact has a single is_subscribed boolean:
  • true — contact is opted in and can receive emails.
  • false — contact has opted out and will be skipped on all sends.
This applies to all send types: transactional, workflow, and campaign.

​
When contacts are subscribed

A contact is created as subscribed by default when:
  • A signup event arrives for a new email.
  • A contact is imported via CSV without an explicit is_subscribed: false.
  • A contact is created via API without explicitly setting subscription state.

​
When contacts are unsubscribed

A contact becomes unsubscribed when:
  • They click an unsubscribe link in a MailerPath email.
  • Their subscription state is explicitly set to false via the API.
  • They are imported via CSV with is_subscribed: false.
When unsubscribing via CSV or API, you should also provide:
  • unsubscribed_at: the timestamp of the opt-out.
  • unsubscribe_reason: a short label for why (e.g., manual opt out, bounced, user request).

​
How skipped sends are recorded

When a send is skipped due to unsubscribe state, MailerPath creates a sent email record with:
  • status: skipped
  • error_message or skip reason indicating contact is unsubscribed
This is visible in the sent email history and in the contact journey timeline as a subscription entry.

​
Re-subscribing a contact

To re-subscribe a contact, update their subscription state via PATCH /client/contacts/{id}/subscription: 
{
  "is_subscribed": true
}
Only re-subscribe contacts who have explicitly opted back in. Re-subscribing without consent violates email compliance requirements. MailerPath automatically injects an unsubscribe URL into every email via the {{unsubscribeUrl}} template variable. When a recipient clicks this link:
  1. MailerPath marks the contact as is_subscribed: false.
  2. All pending workflow queue items for the contact are cancelled.
  3. Subsequent send attempts are skipped automatically.
If your client settings define a custom unsubscribe_url, that URL is used instead of the built-in public unsubscribe endpoint.

​
Subscription state in CSV imports

When importing contacts:
FieldRequired when
is_subscribedAlways recommended
unsubscribed_atRequired when is_subscribed: false
unsubscribe_reasonRequired when is_subscribed: false
Example CSV row for an unsubscribed contact: 
email,is_subscribed,unsubscribed_at,unsubscribe_reason
user@example.com,false,2026-05-01T10:00:00Z,user request

​
Impact on workflows

When a contact unsubscribes:
  • All queued workflow executions for that contact are cancelled.
  • New events will not trigger new workflow executions.
  • The contact remains in the system but is excluded from all future sends.

​
Impact on campaigns

Unsubscribed contacts are excluded during audience materialization. Even if a contact matches the campaign audience (by tag, filter, or explicit contact ID), they will not receive the email if is_subscribed: false.

​
Compliance notes

  • Always include {{unsubscribeUrl}} in campaign and workflow templates.
  • Never re-subscribe contacts without explicit consent from the recipient.
  • Keep unsubscribed_at and unsubscribe_reason accurate for audit purposes.