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

# Subscription management

> How subscription state works, how it affects sends, and how to handle opt-in and opt-out correctly.

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`:

```json theme={null}
{
  "is_subscribed": true
}
```

Only re-subscribe contacts who have explicitly opted back in. Re-subscribing without consent violates email compliance requirements.

## Unsubscribe link behavior

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:

| Field                | Required when                        |
| -------------------- | ------------------------------------ |
| `is_subscribed`      | Always recommended                   |
| `unsubscribed_at`    | Required when `is_subscribed: false` |
| `unsubscribe_reason` | Required 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.

## Related pages

* [Contacts](/documentation/core-functionalities/contacts)
* [Templates and personalization](/documentation/core-functionalities/templates)
* [Brand and sender settings](/documentation/settings/brand-and-sender)
* [Sent emails and delivery](/documentation/send/sent-emails-and-delivery)