From b4404f698ec28a59f32d728c15c59c8b7765d377 Mon Sep 17 00:00:00 2001 From: Dries Augustyns Date: Mon, 9 Feb 2026 18:45:01 +0100 Subject: [PATCH] docs: update contacts documentation to include subscription state and email delivery rules --- apps/wiki/content/docs/concepts/contacts.mdx | 30 +++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/apps/wiki/content/docs/concepts/contacts.mdx b/apps/wiki/content/docs/concepts/contacts.mdx index 318d857..cbfade7 100644 --- a/apps/wiki/content/docs/concepts/contacts.mdx +++ b/apps/wiki/content/docs/concepts/contacts.mdx @@ -43,4 +43,32 @@ Certain keys are reserved by the system and automatically set by Plunk: ### Special keys | Key | Description | |-----|-------------| -| locale | The contact's preferred locale in ISO 639 (e.g. 'en', 'fr', 'es'). Specifying the locale field on a contact will override the project-wide locale for contact-facing pages and email footers | \ No newline at end of file +| locale | The contact's preferred locale in ISO 639 (e.g. 'en', 'fr', 'es'). Specifying the locale field on a contact will override the project-wide locale for contact-facing pages and email footers | + +## Subscription State + +Every contact has a `subscribed` field that determines which types of emails they will receive. A newly created contact is subscribed by default. + +### How contacts become unsubscribed + +A contact can become unsubscribed in several ways: +- **Manually** through the dashboard or via the API +- **Self-service** by clicking the unsubscribe link in an email +- **Automatically** when an email to the contact bounces or results in a complaint + +### Emails by subscription state + +The subscription state controls whether a contact receives marketing emails. Transactional emails are always delivered regardless of subscription state. + +| Email type | Subscribed | Unsubscribed | +|---|---|---| +| **Transactional** (via [/v1/send](/api-reference/public-api/sendTransactionalEmail)) | Delivered | Delivered | +| **Campaigns** | Delivered | Not delivered | +| **Automations** (transactional template) | Delivered | Delivered | +| **Automations** (marketing template) | Delivered | Not delivered | + + +Even when using the transactional API endpoint (`/v1/send`), you cannot send a marketing template to an unsubscribed contact. Use a transactional template instead if the email must reach unsubscribed contacts. + \ No newline at end of file