", "operator": "memberOfSegment" },
{ "field": "data.lifetimeValue", "operator": "greaterThanOrEqual", "value": 500 }
]
}
]
}
```
## Related
Static vs dynamic segments, membership tracking, and entry / exit events.
How `data.*` fields are typed and used in filters.
---
### Apps Wiki Content Docs Guides Template Language (`apps/wiki/content/docs/guides/template-language.mdx`)
---
title: Template language
description: Use conditionals, loops and filters in subjects and bodies with Liquid
icon: Braces
---
Plunk renders email subjects and bodies with [Liquid](https://liquidjs.com/), the template language used by Shopify, Zendesk and Netlify. Every `{{variable}}` placeholder Plunk has always supported keeps working exactly as before — Liquid adds conditionals, loops and filters on top.
The main thing this buys you is fewer campaigns. Instead of one campaign per segment, a single campaign can cover the whole combinatorial space: three languages × two offers is one send with branching copy rather than six sends to compare.
## Variables
Reference any contact field by name. Custom fields under `data` are available both with and without the prefix:
```html
Hi {{firstName}}, you are on the {{plan}} plan.
Same thing: {{data.firstName}} / {{data.plan}}
```
These are always available regardless of contact data:
| Variable | Description |
| -------------------- | -------------------------------------- |
| `{{id}}` | The contact's unique identifier |
| `{{email}}` | The contact's email address |
| `{{locale}}` | The contact's preferred locale |
| `{{subscribed}}` | Subscription status |
| `{{unsubscribeUrl}}` | URL to the unsubscribe page |
| `{{subscribeUrl}}` | URL to the subscribe/resubscribe page |
| `{{manageUrl}}` | URL to the preferences management page |
A variable that isn't set renders as an empty string — it never errors and never leaks the placeholder into the email.
### Fields whose names contain spaces
CSV imports build field names from your column headers, so a "First Name" column becomes the field `first name`. Reference it directly, or with a bracket lookup if you want to combine it with filters:
```html
Hi {{first name}}
Hi {{data["first name"] | capitalize}}
```
## Fallbacks
`?? fallback` is Plunk-specific shorthand and takes a literal:
```html
Hi {{firstName ?? there}}, welcome back.
```
Liquid's `default` filter is the general form and can fall back to another variable:
```html
Hi {{firstName | default: nickname}}
```
Both treat a missing, `null`, `false` or empty value as "not set".
## Conditionals
`if` / `elsif` / `else`, `unless`, and `case` / `when` all work. This is the multilanguage pattern:
```html
{% if locale == 'es' %}
Hola {{firstName ?? cliente}}
{% elsif locale == 'fr' %}
Bonjour {{firstName ?? client}}
{% else %}
Hi {{firstName ?? there}}
{% endif %}
```
And the segment-specific-offer pattern, without splitting the campaign:
```html
{% case plan %}
{% when 'pro' %}Here's 20% off your renewal.
{% when 'free' %}Upgrade now and save 20%.
{% else %}Thanks for being with us.
{% endcase %}
```
Comparison (`==`, `!=`, `>`, `<`, `>=`, `<=`), boolean (`and`, `or`), `contains`, and `blank` / `empty` are all available:
```html
{% if lifetimeValue > 500 and plan != 'free' %}
You qualify for our VIP tier.
{% endif %}
```
Plunk uses JavaScript truthiness rather than Liquid's stricter rules, because imported
contact data very often has a column present but blank. An empty string is falsy, so
`{% if firstName %}` is false for a contact whose `firstName` is `""`.
## Loops
Iterate arrays stored on a contact or passed to `/v1/send`:
```html
{% for item in cartItems %}
- {{forloop.index}}. {{item.name}} — {{item.price}}
{% endfor %}
```
`forloop.index`, `.index0`, `.first`, `.last` and `.length` are available inside the loop, and `limit` / `offset` / `reversed` work on the `for` tag itself.
Outputting an array directly — `{{items}}` — wraps each entry in an `` element. This predates Liquid support and is kept for compatibility; prefer an explicit `{% for %}` so you control the markup.
## Filters
Filters transform a value with `|`. The [full LiquidJS filter list](https://liquidjs.com/filters/overview.html) applies; these come up most:
| Filter | Example | Result |
| ----------------------------------------- | --------------------------------------- | ------------- |
| `upcase` / `downcase` | `{{plan \| upcase}}` | `PRO` |
| `capitalize` | `{{firstName \| capitalize}}` | `Ada` |
| `default` | `{{firstName \| default: "there"}}` | `there` |
| `date` | `{{signupDate \| date: "%B %-d, %Y"}}` | `May 6, 2026` |
| `plus` / `minus` / `times` / `divided_by` | `{{price \| times: 0.8 \| round: 2}}` | `40` |
| `join` | `{{tags \| join: ", "}}` | `a, b` |
| `truncate` | `{{bio \| truncate: 40}}` | truncated |
For `date` to work, store the value as a full ISO 8601 string (see [Custom fields](/guides/custom-fields)).
## Computed values
`assign` and `capture` let you derive a value once and reuse it — useful when an offer depends on something other than a raw field:
```html
{% assign discount = lifetimeValue | divided_by: 20 %}
{% if discount > 25 %}{% assign discount = 25 %}{% endif %}
Here's {{discount}}% off, calculated from your account history.
```
## Escaping template syntax
To show `{{ }}` literally in an email, wrap it in `raw`:
```html
{% raw %}Use {{firstName}} to personalise your own emails.{% endraw %}
```
## What isn't available
`{% include %}`, `{% render %}` and `{% layout %}` are rejected.
## Errors
Saving a template or campaign whose syntax Liquid can't parse returns `400` with the line and column of the problem, so mistakes surface while you're editing.
`/v1/send` is not checked this way. Transactional bodies are usually generated by another system, so an inline `subject` or `body` is always accepted and rendered on a best-effort basis — markup Liquid can't parse falls through to plain `{{variable}}` substitution instead of failing the request.
Rendering itself is deliberately forgiving — nothing about a template can fail a send:
- An unknown variable renders empty.
- An unknown filter is skipped and the value passes through unchanged.
- If a stored template somehow can't be parsed at send time, Plunk falls back to plain `{{variable}}` substitution rather than dropping the email.
## Notes for existing templates
Templates written before Liquid keep rendering the same output in almost every case — plain placeholders, nested paths, `?? fallback`, missing variables and bare arrays are all unchanged. These are the cases that do render differently:
**Fixes to previously wrong output**
- A quoted fallback no longer leaks its quotes. `{{name ?? 'there'}}` used to render `'there'` — quotes included — and now renders `there`, which is what this guide always described.
- Falsy values render instead of disappearing. `0`, `false` and `NaN` used to come out as an empty string; `{{count}}` for a contact with `count: 0` now renders `0`, and `{{subscribed}}` renders `false`. Use `{% unless subscribed %}` to branch on it.
- A fallback containing `??` inside quotes is no longer truncated at the first `??`.
- Placeholders spanning multiple lines, and array indexes like `{{items.0}}`, now resolve; both used to render as literal text or empty.
**Behaviour to check before upgrading**
- Balanced tag markup in body copy is now executed. Prose like `Write {% if x %}…{% endif %} to branch` used to print verbatim and now evaluates to nothing. Wrap it in `{% raw %}` to keep it as text. Unbalanced markup — `Use {% if x %} in docs` — still fails to parse and survives untouched.
- A custom field whose name contains `|`, quotes or other operator characters is now parsed as an expression. Field names made of letters, digits, `_`, `-`, `.` and spaces are unaffected.
## What's next
Store the data your templates branch on.
How templates fit into campaigns, workflows and `/v1/send`.
Set a `locale` per contact to drive multilanguage templates.
---
### Apps Wiki Content Docs Guides Tracking (`apps/wiki/content/docs/guides/tracking.mdx`)
---
title: Tracking
description: Track opens and clicks on the emails you send through Plunk
icon: HatGlasses
---
Plunk provides built-in tracking for email opens and link clicks so you can monitor engagement and drive workflows or segments off email activity.
## Open tracking
When open tracking is enabled, Plunk includes a small invisible tracking pixel at the bottom of your email. When the recipient's mail client loads the pixel, the open is recorded as an `email.open` event on the contact.
### Considerations
- Open tracking depends on the mail client loading remote images. If a contact has images disabled, no open is recorded.
- Some clients (and corporate mail security gateways) pre-fetch images, which can produce false positive opens.
- Apple Mail Privacy Protection masks individual opens — opens from Apple Mail are recorded but reflect proxy fetches rather than human reads.
## Click tracking
When click tracking is enabled, Plunk rewrites links in your email body to route through a tracking redirect. When a contact clicks a link, Plunk records the click and the original URL on an `email.click` event before forwarding the contact to the destination.
### Considerations
- Some mail clients and security tools pre-scan links, which can produce false positive clicks.
- The rewrite is transparent to recipients but means link URLs in the email source no longer match the original destination.
## Configuration
Tracking is configured per project under **Settings → Tracking**. Three modes are available:
| Mode | Behaviour |
| ---------------- | ------------------------------------------------------------------------------------------ |
| **Enabled** | Tracking is applied to every email. |
| **Disabled** | No tracking is applied to any email. |
| **Marketing only** | Tracking is applied to marketing sends (campaigns and emails sent by workflow steps using marketing or headless templates). Transactional sends — anything via `/v1/send` using a transactional template, or campaigns of type `TRANSACTIONAL` — are sent without tracking. |
Tracking is **all or nothing** within a single send — there's no separate toggle for opens vs clicks. Pick the mode that fits your privacy and analytics requirements.
On self-hosted instances, the Marketing-only mode is only available when a no-tracking configuration set is configured. See [Self-hosting → Email setup](/self-hosting/email-setup) for details.
---
### Apps Wiki Content Docs Guides Unsubscribe Pages (`apps/wiki/content/docs/guides/unsubscribe-pages.mdx`)
---
title: Unsubscribe & preferences pages
description: Plunk's hosted pages for letting recipients unsubscribe, resubscribe, and manage their email preferences
icon: UserX
---
Every email Plunk sends to a recipient who can unsubscribe (marketing or headless templates) carries a personalized link to a hosted page where they can manage their subscription. You don't need to build any of this — Plunk hosts the pages, handles the state changes, and tracks the events for you.
## The three URL variables
Three template variables are auto-injected on every send and resolve to per-recipient signed URLs:
| Variable | Page it links to | What the recipient can do |
| -------------------- | ----------------------------------------------------------------- | -------------------------------------------------------- |
| `{{unsubscribeUrl}}` | One-click unsubscribe page | Confirm they want to stop receiving marketing emails |
| `{{subscribeUrl}}` | Resubscribe page | Opt back in after previously unsubscribing |
| `{{manageUrl}}` | Preferences page | View their current state and toggle subscription either way |
Use them anywhere in a template's body or subject line. The placeholder is replaced with a unique URL when the email is rendered for that specific contact.
## Default behaviour by template type
Where Plunk drops these links depends on the template type:
| Template type | Auto footer with `{{unsubscribeUrl}}`? | Notes |
| ----------------- | -------------------------------------------- | ---------------------------------------------------------------------- |
| **Marketing** | Yes — Plunk appends a localized footer | You don't need to do anything. The footer respects the recipient's `locale`. |
| **Headless** | No | You must include `{{unsubscribeUrl}}` (or `{{manageUrl}}`) in your body or the recipient has no way to opt out. |
| **Transactional** | No | Transactional emails skip subscription checks; an unsubscribe link is not added (and shouldn't be needed). |
If you build your own footer in a marketing template, you can still rely on the auto-injected one or override it by including your own link with `{{unsubscribeUrl}}`.
## Inside transactional sends
`/v1/send` accepts the same template variables. Whether an unsubscribe footer is appended depends on the template you reference:
- Sending with no template (just `subject` + `body`) → no auto footer.
- Sending with a marketing template → footer auto-injected.
- Sending with a headless or transactional template → no footer (you control the body).
You can always reference `{{unsubscribeUrl}}` / `{{manageUrl}}` in your inline body if you want to render your own link.
## What happens when the recipient acts
When the recipient clicks one of the links and confirms:
| Action | Effect |
| ----------------------- | --------------------------------------------------------------------------------- |
| Unsubscribe | Contact's `subscribed` flips to `false`. `contact.unsubscribed` event fires. |
| Snooze | Contact's `subscribed` flips to `false` and `snoozedUntil` is set. `contact.unsubscribed` event fires with `reason: "snooze"`. |
| Resubscribe | Contact's `subscribed` flips to `true`. `contact.subscribed` event fires. |
| Update via preferences | Same as above, depending on which way they toggle. |
You can drive workflows off `contact.unsubscribed` / `contact.subscribed` (e.g. send a "we're sorry to see you go" survey, or trigger a winback when they re-opt-in).
## Snoozing
Not everyone who clicks unsubscribe wants to leave for good. Some are mid-launch-sequence, some are going on holiday, and some just want the volume to stop for a while. If the only option is permanent, a share of them take it — and a share of the rest reach for the spam button instead, which costs you far more.
So the unsubscribe and preferences pages offer a second, secondary option: **snooze**. The recipient picks a window, receives nothing for its duration, and is resubscribed automatically when it ends.
| Window | Value passed to the API |
| ---------- | ----------------------- |
| 2 weeks | `2_weeks` |
| 1 month | `1_month` |
| 6 months | `6_months` |
| 1 year | `1_year` |
Snooze is deliberately the quieter of the two choices. Unsubscribe keeps its position and weight on the page; a recipient who came to leave never has to hunt for the button that does it.
### It is a real opt-out, not a softer one
A snoozed contact has `subscribed: false` for the whole window. Every send path — campaigns, workflows, and marketing templates sent through `/v1/send` — filters on that flag, so a snoozed contact receives nothing at all until they come back. Nothing is "held back and delivered later".
The contact also carries a `snoozedUntil` timestamp. That is the only thing distinguishing a snooze from a permanent unsubscribe, and it exists so the return can be scheduled — it plays no part in whether mail is sent.
### Coming back
A background job resubscribes contacts whose window has elapsed, clears `snoozedUntil`, and fires `contact.subscribed` with `reason: "snooze_expired"`. Returns are processed within a few minutes of the window ending.
A recipient can also come back early: the "resume" link on the preferences page, or any visit to `{{subscribeUrl}}`, ends the snooze immediately.
### What ends a snooze early
Any other change to a contact's subscription cancels the snooze and takes over — the pending return is dropped, not queued behind it:
- The recipient unsubscribes properly (their snooze becomes permanent — they will not be resubscribed later).
- The recipient, or you, resubscribes them.
- A hard bounce or spam complaint suppresses the address. A suppressed contact is never resurrected by a snooze that was running when it happened.
- `PATCH /contacts/:id` with `subscribed`, a CSV import that sets the column, a bulk action, or a workflow `Update contact` step.
### Reacting to a snooze
Snoozing reuses `contact.unsubscribed` and `contact.subscribed` rather than introducing new event names, so existing workflows, `Wait for event` steps and campaign statistics pick it up with no changes. Branch on the event's `reason` field to tell them apart:
```json
// contact.unsubscribed — the recipient snoozed
{
"reason": "snooze",
"duration": "6_months",
"snoozedUntil": "2027-03-11T09:14:22.104Z"
}
// contact.subscribed — the window ended
{
"reason": "snooze_expired"
}
```
A "sorry to see you go" workflow triggered on `contact.unsubscribed` should check for `reason` and skip the ones that are snoozes — those people have not gone anywhere.
### In campaign stats
A snooze counts toward the campaign's unsubscribe count, the same as a permanent opt-out. It is still a deliberate opt-out that the campaign prompted, and excluding it would let a campaign that burns through goodwill look clean simply because its recipients chose to pause rather than leave.
### In the dashboard
Snoozed contacts show a distinct **Snoozed** badge in the contacts list, with their own option in the Status filter, so they are never counted as churn. A contact's detail page names the date they return, and the activity feed shows the snooze and the later resume as separate entries.
## Knowing which email caused it
The links Plunk generates at send time carry an `?e=` parameter identifying the message they were sent in — on the `List-Unsubscribe` header, the auto-injected marketing footer, and the `{{unsubscribeUrl}}` / `{{subscribeUrl}}` / `{{manageUrl}}` variables. When the recipient acts, that email is recorded on the resulting event, and the activity feed names the campaign or workflow the opt-out came from.
The parameter is carried across the hosted pages, so a recipient who lands on the preferences page and then unsubscribes is still attributed to the email they started from.
A few cases are unattributed by design:
- Links rendered before the email row exists — a campaign body's `{{unsubscribeUrl}}`, which is rendered once per recipient at queue time rather than at send time.
- Changes with no email behind them: the dashboard toggle, a CSV import, and `PATCH /contacts/:id`.
- Mail sent before this parameter existed.
Attribution is what lets a campaign report how many subscribers it cost: see [campaign stats](/concepts/campaigns#stats).
If you build your own opt-out surface, you can append `?e=` yourself. The value is advisory — Plunk verifies the email belongs to the contact before recording it, and the contact id in the path is what governs the change, so a missing or wrong value costs attribution and nothing else.
## Localization
The hosted pages and the auto-injected footer are localized into the contact's `locale` if set, or the project's default language otherwise. See [Localization](/guides/localization) for the full list of supported languages.
## Branding
The pages name you by your **project name**, inside the copy itself: a recipient sees "Stop receiving emails from **Acme** at **jane@example.com**?", not a logo or header. The same name already appears in the auto-injected marketing footer ("you agreed to receive emails from Acme").
Because recipients read it, use the name they know you by. A project called `Test` or `acme-prod-eu` is shown to them exactly as written. You can rename a project in its settings.
A small "Sent with Plunk" line below the page credits Plunk as the mail provider.
For full control over the look, send marketing as **headless** templates and build the unsubscribe surface into your own product UI. Link your in-product controls to the same `{{unsubscribeUrl}}` for one-click revocation.
## API reference
If you need to drive subscription changes programmatically rather than through the hosted pages — for example because you've built your own preferences UI — use the contacts API:
- `PATCH /contacts/:id` with `{ "subscribed": false }` — unsubscribe a contact.
- `PATCH /contacts/:id` with `{ "subscribed": true }` — resubscribe.
Both flips automatically emit the corresponding `contact.subscribed` / `contact.unsubscribed` event, just like the hosted pages do. Either one also clears a running snooze.
Snoozing from your own preferences UI uses the same unauthenticated endpoint the hosted pages do:
```http
POST /contacts/public/:id/snooze?e=
Content-Type: application/json
{ "duration": "6_months" }
```
It responds with the contact's `subscribed` and `snoozedUntil`. As with the other public list-management routes, the contact id in the path is what governs the change and `?e=` is advisory attribution only.
---
### Apps Wiki Content Docs Guides Verifying Domains (`apps/wiki/content/docs/guides/verifying-domains.mdx`)
---
title: Verifying domains
description: Ensure your emails reach the inbox by verifying your sending domains
icon: Globe
---
Verifying your domain is a requirement to send emails through Plunk. Domain verification helps improve email deliverability and ensures that your emails are less likely to be marked as spam.
## Verifying a domain
You can verify a domain by adding it in the domain tab of the project settings. Once added, Plunk will provide you with the necessary DNS records to add to your domain's DNS settings.
Once you have added the DNS records, it may take some time for the changes to propagate. You can check the verification status in the domain tab of the project settings.
## DNS Records
Domain verification requires adding several DNS records to your domain. Each record serves a specific purpose in email authentication and delivery.
### DKIM Records (3 CNAME records)
**DomainKeys Identified Mail (DKIM)** adds a digital signature to your emails, proving they haven't been tampered with during transit.
You'll need to add **3 CNAME records** provided by Plunk. These records contain cryptographic keys that email receivers use to verify your emails are authentic.
**Why it matters:**
- Prevents email spoofing and tampering
- Improves deliverability and inbox placement
- Required by most email providers (Gmail, Outlook, etc.)
### SPF Record (1 TXT record)
**Sender Policy Framework (SPF)** specifies which mail servers are authorized to send emails on behalf of your domain.
You'll need to add **1 TXT record** that lists the authorized sending servers.
**Why it matters:**
- Prevents unauthorized servers from sending emails using your domain
- Reduces the likelihood of your domain being used for spam
- Works together with DKIM for complete authentication
A domain can only have **one** SPF TXT record. If you already use another email provider (Google Workspace, Microsoft 365, another sending platform), you must **merge** Plunk's SPF mechanism into your existing record — don't add a second SPF record. For example, if your existing record is `v=spf1 include:_spf.google.com ~all`, the merged version is `v=spf1 include:_spf.google.com include:<Plunk's include from the dashboard> ~all`. Two separate SPF records will cause both to fail.
### Bounce Handling (1 MX record)
This **MX record** allows Plunk to receive bounce notifications and spam complaints from email providers.
**Why it matters:**
- Automatically tracks which contacts have bounced or complained
- Helps maintain your sender reputation
- Prevents sending to invalid email addresses
- Required for deliverability monitoring
This MX record handles delivery feedback (bounces, complaints) for emails Plunk sends out — it's separate from the [inbound MX record](/guides/receiving-emails) used to **receive** emails sent to your domain. They serve different purposes; you can have either one or both.
### DMARC (optional, recommended)
**Domain-based Message Authentication, Reporting and Conformance (DMARC)** tells receiving mail servers what to do when an email fails SPF or DKIM checks, and where to send authentication reports.
Plunk doesn't require DMARC, but most major mailbox providers (Gmail, Yahoo, Microsoft) now expect it for bulk senders. Add a TXT record at `_dmarc.yourdomain.com`:
```
v=DMARC1; p=none; rua=mailto:dmarc-reports@yourdomain.com
```
Start with `p=none` to monitor without affecting delivery. Once you've reviewed reports for a couple of weeks and confirmed all your legitimate senders are authenticated, tighten to `p=quarantine` and eventually `p=reject`.
### MAIL FROM domain (optional)
You can configure a custom MAIL FROM domain (typically a subdomain like `mail.yourdomain.com`) so the bounce envelope address aligns with your sending domain. This improves DMARC alignment and is required by some inbox providers for full pass-through.
If you set this up, you'll need an additional MX record and TXT record on the subdomain — Plunk's dashboard will show you the exact values to add when you enable it on a verified domain.
## Verification Status
After adding all DNS records, Plunk automatically checks verification status in the background. Verification typically completes within a few minutes, but can take up to 72 hours depending on DNS propagation.
You can check the status in the Domains section of your project settings. Each record type will show as verified once detected. If you've just added a record and don't want to wait, you can trigger a re-check from the dashboard.
## Troubleshooting
import {Accordion, Accordions} from 'fumadocs-ui/components/accordion';
If your DNS records aren't verifying after 24 hours:
1. **Double-check the values**: ensure you copied the exact values without extra spaces.
2. **Check DNS propagation**: use tools like `dig` or online DNS checkers to verify the records are published.
3. **TTL settings**: some DNS providers cache records. Try lowering the TTL (Time To Live) value.
4. **Contact your DNS provider**: some providers have specific requirements or interfaces for adding these record types.
Even with a verified domain, emails may go to spam if:
- Your content triggers spam filters (excessive links, suspicious keywords).
- Your sender reputation is new or low.
- Recipients have marked your emails as spam in the past.
- You're sending to invalid or unengaged contacts.
Follow email best practices and maintain good [list hygiene](/guides/list-hygiene) to improve deliverability.
---
### Apps Wiki Content Docs Guides Webhooks (`apps/wiki/content/docs/guides/webhooks.mdx`)
---
title: Webhooks
description: Send real-time event data from Plunk to your own application using webhooks
icon: Webhook
---
import {Tab, Tabs} from 'fumadocs-ui/components/tabs';
import {TypeTable} from 'fumadocs-ui/components/type-table';
Plunk can send real-time HTTP requests to your application when specific events occur, such as email bounces, spam complaints, or custom events. This is done by creating a [workflow](/concepts/workflows) that uses the **Webhook** step to forward event data to your own endpoint.
## How it works
Webhooks in Plunk are powered by the workflow system. The basic flow is:
1. An event occurs in Plunk (e.g. an email bounces, a contact subscribes, or a custom event is tracked)
2. A workflow is triggered by that event
3. The workflow executes a **Webhook** step, sending an HTTP request to your URL with relevant data
This means you can receive notifications for any event Plunk tracks, including both system events and your own custom events.
## Internal events
Plunk automatically tracks a set of internal events that you can use as workflow triggers. These events cannot be manually tracked via the API — they are generated by the system.
### Email events
| Event | Description |
| ----------------- | -------------------------------------------------------------------------------------------------------- |
| `email.sent` | An email was successfully sent |
| `email.delivery` | An email was delivered to the recipient |
| `email.open` | A contact opened an email for the first time |
| `email.click` | A contact clicked a link in an email for the first time |
| `email.bounce` | An email bounced (hard or soft bounce) |
| `email.complaint` | A contact marked an email as spam |
| `email.received` | An email was received at your verified domain (requires [inbound email setup](/guides/receiving-emails)) |
### Contact events
| Event | Description |
| ---------------------- | ------------------------------------------------------- |
| `contact.subscribed` | A contact's subscription status changed to subscribed |
| `contact.unsubscribed` | A contact's subscription status changed to unsubscribed |
### Segment events
| Event | Description |
| ---------------------- | --------------------------- |
| `segment..entry` | A contact entered a segment |
| `segment..exit` | A contact exited a segment |
Segment events use a slugified version of the segment name. For example, a segment called "VIP Users" would produce
the events `segment.vip-users.entry` and `segment.vip-users.exit`.
## Setting up a webhook
import {Step, Steps} from 'fumadocs-ui/components/steps';
### Create the workflow
Navigate to the **Workflows** section in the dashboard and create a new workflow. Choose the event you want to listen for as the trigger. For example, to receive notifications when an email bounces, use `email.bounce` as the trigger event.
### Add a Webhook step
After the trigger, add a **Webhook** step and configure it:
- **URL**: The endpoint on your server that will receive the webhook (e.g. `https://api.example.com/webhooks/plunk`)
- **Method**: The HTTP method to use. Defaults to `POST`, which is recommended for most use cases.
- **Headers** (optional): Custom headers to include in the request, provided as JSON. This is useful for authentication.
```json
{
"Authorization": "Bearer your-secret-token"
}
```
- **Body** (optional): Custom request body. When omitted, Plunk sends the [default payload](#webhook-payload) shown below. When provided, the value replaces the default payload entirely and is JSON-encoded before being sent.
### Use variables in the request (optional)
The `url`, header values, and `body` all support `{{variable}}` interpolation. The available scope is the same as `SEND_EMAIL` templates, plus a webhook-only `event` namespace exposing the trigger event payload:
| Variable | Value |
| --------------------------------------------------------- | --------------------------------------------------------------------------- |
| `{{id}}`, `{{email}}` | The contact's ID and email. |
| `{{}}` (top-level) | Any key from the contact's `data` JSON (e.g. `{{firstName}}`, `{{plan}}`). |
| `{{data.}}` | The same contact data, addressed via the `data` namespace. |
| `{{event.}}` | Webhook-only. Fields from the trigger event payload (e.g. `{{event.subject}}`). |
| `{{}}` (from execution context) | Keys passed in as `context` when starting a `MANUAL` execution. |
| `{{unsubscribeUrl}}`, `{{subscribeUrl}}`, `{{manageUrl}}` | Per-contact subscription management URLs. |
The HTTP `method` is **not** templated — it must be a literal verb (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`). The `url` must include a static scheme (`http://` or `https://`); placeholders are supported inside the URL but cannot replace the scheme.
Example — forward a contact event to your own API, parameterised by contact data:
**URL**
```text
https://api.example.com/users/{{id}}/events
```
**Headers**
```json
{
"Authorization": "Bearer your-secret-token"
}
```
**Body**
```json
{
"email": "{{email}}",
"plan": "{{plan}}",
"referrer": "{{event.referrer}}"
}
```
### Enable the workflow
Once configured, enable the workflow. It will start sending webhook requests whenever the trigger event occurs.
## Webhook payload
When using the default payload (no custom body configured), Plunk sends a JSON request with the following structure:
```json
{
"contact": {
"email": "user@example.com",
"subscribed": true,
"data": {
"name": "John",
"plan": "pro"
}
},
"workflow": {
"id": "wf_abc123",
"name": "Bounce Notifications"
},
"execution": {
"id": "exec_xyz789",
"startedAt": "2025-01-15T10:30:00.000Z"
},
"event": {
"subject": "Welcome to Plunk",
"from": "hello@example.com",
"fromName": "Plunk Team",
"messageId": "ses-message-id",
"emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf",
"templateId": null,
"campaignId": "camp_abc123",
"sourceType": "CAMPAIGN",
"bounceType": "Permanent",
"bouncedAt": "2025-01-15T10:30:00.000Z"
}
}
```
The `event` field contains the data associated with the event that triggered the workflow. The exact contents depend on the event type.
### Event data by type
#### Email events
Most email events share a common set of base fields:
In addition to these base fields, each event includes the following event-specific fields. The base fields above (`subject`, `from`, `fromName`, `messageId`, `emailId`, `templateId`, `campaignId`, `sourceType`) are present on every email event in addition to the event-specific fields shown below.
```json
{
"subject": "Welcome to Plunk",
"from": "hello@example.com",
"fromName": "Plunk Team",
"messageId": "ses-message-id",
"emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf",
"templateId": null,
"campaignId": null,
"sourceType": "TRANSACTIONAL",
"sentAt": "2025-01-15T10:30:00.000Z"
}
```
```json
{
"subject": "Welcome to Plunk",
"from": "hello@example.com",
"fromName": "Plunk Team",
"messageId": "ses-message-id",
"emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf",
"templateId": null,
"campaignId": "camp_abc123",
"sourceType": "CAMPAIGN",
"deliveredAt": "2025-01-15T10:30:05.000Z"
}
```
```json
{
"subject": "Welcome to Plunk",
"from": "hello@example.com",
"fromName": "Plunk Team",
"messageId": "ses-message-id",
"emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf",
"templateId": null,
"campaignId": null,
"sourceType": "TRANSACTIONAL",
"openedAt": "2025-01-15T11:00:00.000Z",
"opens": 1,
"isFirstOpen": true
}
```
```json
{
"subject": "Welcome to Plunk",
"from": "hello@example.com",
"fromName": "Plunk Team",
"messageId": "ses-message-id",
"emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf",
"templateId": null,
"campaignId": null,
"sourceType": "TRANSACTIONAL",
"link": "https://example.com/pricing",
"clickedAt": "2025-01-15T11:05:00.000Z",
"clicks": 1,
"isFirstClick": true
}
```
Permanent bounce:
```json
{
"subject": "Welcome to Plunk",
"from": "hello@example.com",
"fromName": "Plunk Team",
"messageId": "ses-message-id",
"emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf",
"templateId": null,
"campaignId": null,
"sourceType": "TRANSACTIONAL",
"bounceType": "Permanent",
"bouncedAt": "2025-01-15T10:31:00.000Z"
}
```
Transient (soft) bounce:
```json
{
"subject": "Welcome to Plunk",
"from": "hello@example.com",
"fromName": "Plunk Team",
"messageId": "ses-message-id",
"emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf",
"templateId": null,
"campaignId": null,
"sourceType": "TRANSACTIONAL",
"bounceType": "Transient",
"transientBounce": true
}
```
Only `Permanent` bounces count toward your project's bounce rate and trigger automatic contact unsubscription.
`Transient` bounces are tracked for visibility only.
```json
{
"subject": "Welcome to Plunk",
"from": "hello@example.com",
"fromName": "Plunk Team",
"messageId": "ses-message-id",
"emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf",
"templateId": null,
"campaignId": null,
"sourceType": "TRANSACTIONAL",
"complainedAt": "2025-01-15T10:35:00.000Z"
}
```
This event fires when an email is received at your verified domain. See [Receiving Emails](/guides/receiving-emails) for setup instructions.
```json
{
"messageId": "ses-message-id",
"from": "sender@example.com",
"fromHeader": "Jane Smith ",
"to": "support@yourdomain.com",
"subject": "Re: Your question",
"timestamp": "2025-01-15T10:30:00.000Z",
"recipients": ["support@yourdomain.com"],
"hasContent": true,
"body": "This is the email body content...",
"spamVerdict": "PASS",
"virusVerdict": "PASS",
"spfVerdict": "PASS",
"dkimVerdict": "PASS",
"dmarcVerdict": "PASS",
"processingTimeMillis": 142
}
```
#### Contact events
`contact.subscribed` and `contact.unsubscribed` carry no event data by default. The `event` field will be an empty object `{}`.
The exception is when an unsubscription is triggered automatically by an email bounce or complaint — in that case `event` includes a `reason` field:
```json
{
"reason": "bounce"
}
```
#### Segment events
Both `segment..entry` and `segment..exit` include:
```json
{
"segmentId": "seg_abc123",
"segmentName": "VIP Users"
}
```
#### Custom events
Custom events tracked via the API include whatever data you passed in the `data` field when calling `track`.
#### No event data
For events that carry no data, the `event` field will be an empty object `{}`.
## Correlating webhooks with send requests
All email events include an `emailId` field that matches the Plunk email record ID returned when you send an email via `POST /v1/send`. This allows you to directly correlate webhook events with your API requests.
**Example workflow:**
1. Send email via API:
```json
POST /v1/send
{
"to": "user@example.com",
"subject": "Welcome",
"body": "Hello!"
}
Response:
{
"success": true,
"data": {
"emails": [
{
"contact": {"id": "cnt_abc", "email": "user@example.com"},
"email": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf"
}
]
}
}
```
2. Store the `email` ID (`ac32f08e-c6b9-45d3-9824-a73dff1e3bbf`) in your database
3. When webhook events fire (e.g., `email.open`, `email.bounce`), match them using `event.emailId`:
```json
{
"event": {
"emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf",
"messageId": "ses-message-id",
"openedAt": "2025-01-15T11:00:00.000Z"
}
}
```
This eliminates the need to match by contact email + timestamp or to listen for `email.sent` webhooks just to get the provider `messageId`.
## Common use cases
### Bounce and complaint monitoring
Create a workflow triggered by `email.bounce` or `email.complaint` to forward these events to your application. This allows you to keep your own database in sync with Plunk's contact statuses.
You can use additional workflow steps before the webhook to add logic:
- **Condition**: Only send the webhook for hard bounces by checking the `bounceType` field
- **Delay**: Add a short delay to batch-process related events
- **Update Contact**: Mark the contact with metadata before sending the webhook
### Syncing unsubscribes
Trigger a workflow on `contact.unsubscribed` to notify your application when a contact opts out. This is useful for keeping subscription status synchronized across multiple systems.
### Custom event forwarding
If you track custom events in Plunk (e.g. `user.signup`, `order.completed`), you can forward those same events to other services via webhooks. This turns Plunk into an event router — track once, distribute to multiple endpoints.
## Receiving webhooks safely
Plunk's webhook step has a few characteristics worth knowing when you build the receiving endpoint:
- **Method**: defaults to `POST` with `Content-Type: application/json`. You can override the method per step.
- **Timeout**: each request times out after **10 seconds**. Long-running endpoints should accept the request, queue the work, and return `2xx` quickly.
- **Redirects**: up to 5 redirects are followed. Each hop is re-validated against the SSRF rules below.
- **Public URL required**: your webhook endpoint must be reachable on the public internet. Webhooks pointed at private or internal addresses (loopback, RFC 1918 ranges, etc.) won't be delivered.
- **Schemes**: only `http://` and `https://` are accepted. Prefer HTTPS.
- **No automatic retries**: a non-2xx response or timeout fails the workflow step. Build idempotency into your handler and use workflow logic (a `WAIT_FOR_EVENT` step, a fallback branch) if you need retry semantics.
- **Verify authenticity with a shared secret**: configure a secret header on the webhook step and check it on your endpoint:
```json
// Webhook step → Headers
{
"Authorization": "Bearer your-shared-secret"
}
```
The secret travels with every request from that step. Rotate it like any other shared secret. Prefer this over IP allowlisting — egress IPs can change.
## Adding conditions and delays
Since webhooks are part of the workflow system, you can combine them with other step types for more advanced setups:
- Use a **Condition** step to only fire the webhook when certain criteria are met (e.g. only notify for contacts on a specific plan)
- Use a **Wait for Event** step to wait for a follow-up event before sending the webhook (e.g. wait to see if a bounced contact re-subscribes)
- Use a **Delay** step to add a time buffer before the webhook fires
---
### Apps Wiki Content Docs Recipes Double Opt In (`apps/wiki/content/docs/recipes/double-opt-in.mdx`)
---
title: Double opt-in
description: Require a confirmation click before a new signup starts receiving marketing email
icon: MailCheck
---
Double opt-in adds a confirmation step between "user signs up" and "user starts getting marketing email." It's the standard way to avoid mailing typoed addresses, role accounts, and anyone who didn't actually consent.
The trick is `{{subscribeUrl}}`: a per-contact link Plunk auto-injects into every send. Clicking it flips `subscribed` to `true` and fires a `contact.subscribed` event.
## Setup
import {Step, Steps} from 'fumadocs-ui/components/steps';
### Create two templates
- A **Transactional** template for the confirmation email, containing `{{subscribeUrl}}`:
```html
Hi {{firstName}}, please confirm your email to start receiving updates:
Confirm my email
```
- A **Marketing** template for the welcome email that goes out *after* they confirm.
A marketing template targeted at an unsubscribed contact is [silently skipped](/concepts/contacts#emails-by-subscription-state). Use a transactional template for the confirmation specifically — it bypasses the subscription check.
### Trigger the signup from your backend
Two calls with your secret key (`sk_*`): create the contact unsubscribed, then track the event that fires the confirmation workflow.
```bash
curl https://next-api.useplunk.com/contacts \
-H "Authorization: Bearer sk_your_secret_key" \
-d '{ "email": "ada@example.com", "subscribed": false, "data": { "firstName": "Ada" } }'
curl https://next-api.useplunk.com/v1/track \
-H "Authorization: Bearer sk_your_secret_key" \
-d '{ "event": "signup.pending", "email": "ada@example.com", "subscribed": false }'
```
Both calls pass `subscribed: false`. If you skip the first call and rely on `/v1/track` alone, tracking on an unknown email creates the contact — but defaults it to subscribed, which defeats the point.
### Workflow A: send the confirmation
**Workflows → New workflow**:
- **Trigger**: `EVENT` on `signup.pending`
- `SEND_EMAIL` step → transactional confirmation template
Enable it.
### Workflow B: welcome them after confirmation
**Workflows → New workflow**:
- **Trigger**: `EVENT` on `contact.subscribed`
- `SEND_EMAIL` step → marketing welcome template
Enable it. `contact.subscribed` fires whenever a contact opts in — including via `{{subscribeUrl}}`, the preferences page, or the API — so this workflow handles both first-time confirmations and resubscribes.
## Reminder if they don't confirm
Extend Workflow A with a `WAIT_FOR_EVENT` step after the send:
- **Event**: `contact.subscribed`
- **Timeout**: `86400` (24 hours)
On timeout, send a single reminder (also transactional). Keep the number of reminders small — repeated confirmation prompts look like spam to mailbox providers as much as to recipients.
## What's next
Detail on `{{subscribeUrl}}` and the hosted pages.
The difference between Marketing, Transactional, and Headless templates.
---
### Apps Wiki Content Docs Recipes Meta.Json (`apps/wiki/content/docs/recipes/meta.json`)
{
"pages": ["index", "waitlist", "sync-unsubscribes", "double-opt-in"]
}
---
### Apps Wiki Content Docs Recipes Sync Unsubscribes (`apps/wiki/content/docs/recipes/sync-unsubscribes.mdx`)
---
title: Sync unsubscribes to your database
description: Mirror Plunk's subscription state into your own user table using a workflow + webhook
icon: RefreshCw
---
Every flip of a contact's `subscribed` state — manual edits, the hosted unsubscribe page, bounces, complaints — fires a `contact.unsubscribed` event. Wire a workflow with a `WEBHOOK` step to forward that to your backend.
## Setup
import {Step, Steps} from 'fumadocs-ui/components/steps';
### Build the receiving endpoint
A public HTTPS endpoint that verifies a shared secret and updates the user row. Webhook requests time out after 10 seconds, so do the work async if it's slow.
```ts
app.post('/plunk/unsubscribes', async (req, res) => {
if (req.header('authorization') !== `Bearer ${process.env.PLUNK_WEBHOOK_SECRET}`) {
return res.status(401).end();
}
const { contact, event } = req.body;
await db.user.update({
where: { email: contact.email },
data: {
emailSubscribed: false,
emailUnsubscribedReason: event.reason ?? 'user_action',
},
});
res.status(204).end();
});
```
`event.reason` is `"bounce"` or `"complaint"` for automatic unsubscribes, and absent for manual / self-service ones.
### Create the workflow
**Workflows → New workflow**:
- **Trigger**: `EVENT` on `contact.unsubscribed`
- Add a `WEBHOOK` step:
- **URL**: `https://api.example.com/plunk/unsubscribes`
- **Headers**: `{ "Authorization": "Bearer your-shared-secret" }`
- Leave the body blank to get the [default payload](/guides/webhooks#webhook-payload).
Enable the workflow.
## Mirroring resubscribes
Build a second workflow with the same shape, triggered by `contact.subscribed`. Keep it separate from the unsubscribe flow — two short workflows are easier to monitor than one branched one.
## The reverse direction
If your product is the source of truth (a user toggles their email preference in your settings UI), call `PATCH /contacts/:id` from your backend:
```bash
curl -X PATCH https://next-api.useplunk.com/contacts/cnt_abc \
-H "Authorization: Bearer sk_your_secret_key" \
-d '{"subscribed": false}'
```
That flip also fires `contact.unsubscribed`, meaning your own webhook will round-trip back into your handler. That's usually harmless because the update is idempotent — but be aware of it.
## What's next
Webhook step reference, payload shape, and safety.
The hosted pages and template URL variables.
---
### Apps Wiki Content Docs Recipes Waitlist (`apps/wiki/content/docs/recipes/waitlist.mdx`)
---
title: Waitlist with confirmation email
description: Track signups as a custom event, store everyone who joins as a contact, and automatically email them
icon: ListOrdered
---
A waitlist is the simplest possible Plunk workflow: one tracked event from your app, one workflow that listens for it, one email.
## Setup
import {Step, Steps} from 'fumadocs-ui/components/steps';
### Create the confirmation template
In **Templates → New template**, create a **Marketing** template. Use `{{variable}}` placeholders for anything you want to personalise from contact data:
```text
Subject: You're on the list, {{firstName}}
Hi {{firstName}}, thanks for joining the {{product}} waitlist.
We'll let you know as soon as your spot opens up.
```
### Track the signup from your backend
Call `POST /v1/track` when a user submits the form. Use a secret key (`sk_*`) — never call this from the browser.
```bash
curl https://next-api.useplunk.com/v1/track \
-H "Authorization: Bearer sk_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"event": "waitlist.joined",
"email": "ada@example.com",
"data": { "firstName": "Ada", "product": "Beta" }
}'
```
This call upserts the contact (subscribed by default) and records `waitlist.joined` on them. Anything you put in `data` lands on the contact and is available as `{{firstName}}`, `{{product}}`, etc. in the template.
A workflow's trigger event **cannot be changed after the first execution**. Namespace it (`waitlist.joined`) rather than something generic you might want to reuse.
### Create the workflow
**Workflows → New workflow**:
- **Trigger**: `EVENT` on `waitlist.joined`
- Add a `SEND_EMAIL` step pointing at the template from step 1
Enable the workflow. Workflows are created disabled — until the toggle is on, nothing fires.
## Tagging signups for later
If you want to segment on waitlist signups later, add an `UPDATE_CONTACT` step before the email:
```json
{ "stage": "waitlist", "waitlistSource": "{{event.referrer}}" }
```
You can then build a [segment](/concepts/segments) of contacts where `stage == "waitlist"` to target with follow-up campaigns. This is cleaner than filtering on "ever fired `waitlist.joined`."
## What's next
Step types and trigger semantics.
Full reference for `POST /v1/track`.
---
### Apps Wiki Content Docs Self Hosting Docker (`apps/wiki/content/docs/self-hosting/docker.mdx`)
---
title: Docker Deployment
description: Deploy with Docker Compose
---
## Quick Start
1. Download [docker-compose.yml](https://raw.githubusercontent.com/useplunk/plunk/next/docker-compose.yml)
2. Configure environment variables
3. Run `docker compose up -d`
## Minimal .env
```bash
# Required
JWT_SECRET="$(openssl rand -base64 32)"
DB_PASSWORD="your-secure-password"
# Domains (point these to your server)
API_DOMAIN="api.yourdomain.com"
DASHBOARD_DOMAIN="app.yourdomain.com"
LANDING_DOMAIN="www.yourdomain.com"
WIKI_DOMAIN="docs.yourdomain.com"
USE_HTTPS="true"
# AWS SES
AWS_SES_REGION="us-east-1"
AWS_SES_ACCESS_KEY_ID="your-key"
AWS_SES_SECRET_ACCESS_KEY="your-secret"
SES_CONFIGURATION_SET="plunk-tracking"
```
See [Environment Variables](/self-hosting/environment-variables) for all options.
## Services
| Service | Purpose |
|---------|---------|
| `plunk` | All apps + nginx (API, Web, Landing, Wiki, SMTP) |
| `postgres` | PostgreSQL 16 database |
| `redis` | Redis 7 queue |
| `minio` | S3-compatible storage |
| `ntfy` | Notifications |
## Ports
| Port | Service |
| ----- | ---------------------------------------- |
| 80 | Nginx (HTTP) — fronts API, dashboard, landing, wiki |
| 465 | SMTP (implicit TLS) |
| 587 | SMTP (STARTTLS) |
| 8080 | API server (proxied through nginx; not usually exposed externally) |
| 9000 | Minio API |
| 9001 | Minio web console |
When deploying behind a reverse proxy or load balancer, expose port 80 (and 465/587 if using SMTP). Postgres, Redis, and Minio are kept internal to the Docker network by default.
## Health check
The API exposes a health endpoint at `/health` for orchestrators (Docker Compose, Kubernetes, load balancers):
```bash
curl https://api.yourdomain.com/health
# { "status": "ok", "time": ..., "uptime": ... }
```
Use this for liveness/readiness probes. It returns `200` when the API process is up and able to serve requests.
## Running Individual Services
Set `SERVICE` environment variable:
```bash
SERVICE=api # API only
SERVICE=worker # Worker only
SERVICE=web # Dashboard only
SERVICE=all # Everything (default)
```
## SMTP TLS Certificates
For TLS on ports 465/587, provide certificates via one of these methods:
### Traefik acme.json (Dokploy, Coolify)
Mount the `acme.json` file and set `SMTP_DOMAIN`:
```yaml
environment:
SMTP_DOMAIN: "smtp.yourdomain.com"
volumes:
- /path/to/acme.json:/certs/acme.json:ro
```
Plunk automatically extracts the certificate for `SMTP_DOMAIN` from acme.json. Traefik rewrites `acme.json` in place, so mounting the single file picks up renewals.
### PEM Files
Mount the directory that holds `privkey.pem` and `fullchain.pem`, not the files themselves: a single-file bind mount keeps pointing at the old file once a renewal replaces it.
```yaml
volumes:
- /path/to/certs:/certs:ro
```
### Certbot
Certbot's `live//` files are relative symlinks into `archive/`, and certbot makes both directories readable by root only, while the Plunk container runs as UID 1001. Have certbot copy the files into a certificates directory after every issuance and renewal with a deploy hook, and mount that directory as in [PEM Files](#pem-files):
```bash
certbot certonly -d smtp.yourdomain.com --deploy-hook \
'install -m 644 "$RENEWED_LINEAGE/fullchain.pem" /path/to/certs/ && install -m 600 -o 1001 "$RENEWED_LINEAGE/privkey.pem" /path/to/certs/'
```
For a certificate certbot already manages, add the hook with `certbot reconfigure --cert-name smtp.yourdomain.com --deploy-hook '...'`.
If no certificates are mounted, SMTP runs without TLS.
Certificates issued or renewed while Plunk is running are picked up within about a minute, without restarting the container.
## Building from Source
```bash
docker build -t plunk:custom .
```
---
### Apps Wiki Content Docs Self Hosting Email Setup (`apps/wiki/content/docs/self-hosting/email-setup.mdx`)
---
title: AWS SES Setup
description: Configure email delivery
---
## 1. Create IAM User
1. Go to IAM Console → Users → Create user
2. Name: `plunk-ses`
3. Attach a custom policy with required permissions (see below)
4. Create access keys → Save credentials
### Required IAM Policy
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ses:SetIdentityMailFromDomain",
"ses:GetIdentityDkimAttributes",
"ses:SendRawEmail",
"ses:GetIdentityVerificationAttributes",
"ses:VerifyDomainDkim",
"ses:ListIdentities",
"ses:SetIdentityFeedbackForwardingEnabled"
],
"Resource": "*"
}
]
}
```
## 2. Create SNS Topic
1. Go to SNS Console → Topics → Create topic
2. Type: Standard
3. Name: `plunk-ses-events`
4. Create topic
5. Create subscription:
- Protocol: HTTPS
- Endpoint: `https://api.yourdomain.com/webhooks/sns`
6. Plunk automatically confirms the subscription. If it fails, check your logs for the confirmation URL.
## 3. Create Configuration Sets
### Tracking Configuration Set
1. SES Console → Configuration sets → Create set
2. Name: `plunk-tracking`
3. Add event destination:
- Name: `sns-events`
- Event types: **Sends, Deliveries, Opens, Clicks, Bounces, Complaints**
- Destination: SNS → Select `plunk-ses-events` topic
### No-Tracking Configuration Set
1. Create another set named `plunk-no-tracking`
2. Add event destination with only: **Sends, Deliveries, Bounces, Complaints**
## 4. Configure Environment
```bash
AWS_SES_REGION="us-east-1"
AWS_SES_ACCESS_KEY_ID="your-access-key"
AWS_SES_SECRET_ACCESS_KEY="your-secret-key"
SES_CONFIGURATION_SET="plunk-tracking"
SES_CONFIGURATION_SET_NO_TRACKING="plunk-no-tracking"
```
## 5. Add Your Domain in Plunk
Once you have configured AWS SES with the above settings, you can add and verify your domain directly through the Plunk dashboard. Plunk will handle the domain verification and DKIM setup with AWS SES automatically and show you the right records to add to your DNS.
## 6. (Optional) Configure Inbound Email
If you want to use Plunk's [Receiving emails](/guides/receiving-emails) feature, configure SES inbound separately. Plunk does not auto-provision receipt rules, so this is a manual one-time setup in your AWS account.
Not all AWS regions support SES inbound — confirm `inbound-smtp..amazonaws.com` exists for your `AWS_SES_REGION` before continuing. If your region doesn't support inbound, you can keep outbound on your current region and run a separate identity in a region that does.
### Create a receipt rule set
1. SES Console → **Email receiving** → **Rule sets** → Create rule set (or use an existing one)
2. Add a rule:
- **Recipient conditions**: `*@yourdomain.com` (or specific addresses you want to receive)
- **Actions**: Publish to Amazon SNS topic → select your `plunk-ses-events` topic (or create a separate topic that's also subscribed to `https://api.yourdomain.com/webhooks/sns`)
3. Set the rule set as **active**
### Inbound IAM permissions
Plunk doesn't call SES inbound APIs at runtime — the IAM policy from step 1 covers everything Plunk needs. Configuring receipt rules in AWS is a manual one-time action you do as an AWS admin.
### Add an MX record
For each verified domain you want to receive on, add an MX record pointing at the SES inbound endpoint for your region:
```
Type: MX
Name: yourdomain.com
Value: 10 inbound-smtp..amazonaws.com
```
Plunk's dashboard will show the exact value to use for your configured region.
## 7. (Optional) Move Out of the SES Sandbox
By default, new AWS SES accounts are in **sandbox mode** with strict limits:
- Send only to **verified** addresses
- 200 messages per 24 hours
- 1 message per second
Sandbox is fine for testing but useless for production. Request production access in the SES console (**Account dashboard** → **Request production access**) — AWS typically approves within 24 hours after a short questionnaire about your sending practices.
After approval, your sending quota will reflect a much higher daily and per-second limit specific to your account.
## 8. (Optional) Configure a MAIL FROM Domain
For better DMARC alignment, you can configure a custom MAIL FROM subdomain (e.g. `mail.yourdomain.com`). In the SES console under **Verified identities** → your domain → **MAIL FROM domain**, set a subdomain and add the additional MX and TXT records SES displays. Plunk's IAM policy already includes `ses:SetIdentityMailFromDomain` to support this.
---
### Apps Wiki Content Docs Self Hosting Environment Variables (`apps/wiki/content/docs/self-hosting/environment-variables.mdx`)
---
title: Environment Variables
description: Configuration reference
---
## Security & Database
| Variable | Required | Description | Example |
| -------------- | -------- | ---------------------------------------------------------------------------- | ------------------------------------------------- |
| `JWT_SECRET` | Yes | Secret key used to sign JWT tokens. Generate with `openssl rand -base64 32`. | `s3cr3t...` |
| `DB_PASSWORD` | Yes | PostgreSQL database password. Used by the Docker Compose setup. | `changeme123` |
| `DATABASE_URL` | Yes | Full PostgreSQL connection string used by the application at runtime (typically through PgBouncer). Auto-configured in Docker. | `postgresql://plunk:password@postgres:5432/plunk` |
| `DIRECT_DATABASE_URL` | Yes | Direct PostgreSQL connection string used by Prisma migrations. Must bypass any connection pooler. Auto-configured in Docker. | `postgresql://plunk:password@postgres:5432/plunk` |
| `REDIS_URL` | Yes | Redis connection string. | `redis://redis:6379` |
| `NODE_ENV` | No | Application environment. Set to `production` for production deployments. | `production` |
| `PORT` | No | Port the API server listens on. | `8080` (default) |
## URLs & Domains
Set your subdomains here. The application automatically derives all internal and client-side URLs from these at container startup — you don't need to set `*_URI` or `NEXT_PUBLIC_*` variables manually.
| Variable | Required | Description | Example |
| ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `API_DOMAIN` | Yes | Subdomain for the API server. | `api.yourdomain.com` |
| `DASHBOARD_DOMAIN` | Yes | Subdomain for the dashboard app. | `app.yourdomain.com` |
| `LANDING_DOMAIN` | Yes | Subdomain for the landing page. | `www.yourdomain.com` |
| `WIKI_DOMAIN` | Yes | Subdomain for the documentation site. | `docs.yourdomain.com` |
| `USE_HTTPS` | No | Set to `true` when running behind a TLS-terminating reverse proxy. Used to construct URLs with the correct protocol. | `false` (default) |
## AWS SES
| Variable | Required | Description | Example |
| ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
| `AWS_SES_REGION` | Yes | AWS region where SES is configured. | `us-east-1` |
| `AWS_SES_ACCESS_KEY_ID` | Yes | AWS access key ID with SES send permissions. | `AKIA...` |
| `AWS_SES_SECRET_ACCESS_KEY` | Yes | AWS secret access key for SES. | `wJalr...` |
| `SES_CONFIGURATION_SET` | No | SES configuration set name used for open/click tracking. | `plunk-configuration-set` (default) |
| `SES_CONFIGURATION_SET_NO_TRACKING` | No | A second SES configuration set without tracking. When set, projects can toggle email tracking on/off. If omitted, the tracking toggle is hidden. | `plunk-no-tracking-configuration-set` (default) |
| `MAIL_FROM_SUBDOMAIN` | No | Subdomain prefix used when constructing the MAIL FROM hostname for a verified domain (e.g. with default `plunk` and domain `yourdomain.com`, the MAIL FROM is `plunk.yourdomain.com`). Override when the default subdomain is already in use (e.g. by an R2/CDN custom domain), since the MAIL FROM hostname needs MX + TXT records that can't coexist with a CNAME. | `plunk` |
## Storage (Minio)
The bundled Docker setup includes Minio with defaults that work out of the box. Only change these when connecting to an external S3-compatible bucket.
| Variable | Required | Description | Default |
| ---------------------- | -------- | ------------------------------------------------------------------ | ------------------- |
| `MINIO_ROOT_USER` | No | Minio root username (Docker Compose only). | `plunk` |
| `MINIO_ROOT_PASSWORD` | No | Minio root password (Docker Compose only). | `plunkminiopass` |
| `MINIO_API_PORT` | No | Port for the Minio API (Docker Compose only). | `9000` |
| `MINIO_CONSOLE_PORT` | No | Port for the Minio console UI (Docker Compose only). | `9001` |
| `S3_ENDPOINT` | No | S3 or Minio endpoint URL. | `http://minio:9000` |
| `S3_ACCESS_KEY_ID` | No | S3 or Minio access key. | — |
| `S3_ACCESS_KEY_SECRET` | No | S3 or Minio secret key. | — |
| `S3_BUCKET` | No | Bucket name for file uploads. | `uploads` |
| `S3_PUBLIC_URL` | No | Publicly accessible base URL for stored files. | — |
| `S3_FORCE_PATH_STYLE` | No | Use path-style URLs instead of virtual-hosted. Required for Minio. | `true` |
| `S3_PREFIX` | No | Upload folder in the bucket; only it is made publicly readable. | — |
Setting `S3_PREFIX` on an instance that already has uploads breaks every image uploaded before it. The bucket
policy is replaced to only make objects under the prefix publicly readable, so files at the bucket root (already
embedded in templates, campaigns and sent emails) start returning 403. Moving them under the prefix doesn't help,
since that changes their URLs. Only set it on a new install. `S3_PUBLIC_URL` must still point at the bucket root,
since the prefix is appended to it.
## Attachments
Plunk supports attachments on transactional emails. AWS SES caps total message size at 40 MB; the defaults below leave headroom but can be tuned for your use case.
| Variable | Required | Description | Default |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------ | ------- |
| `MAX_ATTACHMENT_SIZE_MB` | No | Maximum total attachment size in megabytes per email. Hard upper bound enforced by AWS SES is 40 MB. | `10` |
| `MAX_ATTACHMENTS_COUNT` | No | Maximum number of attachments per email. | `10` |
## API Rate Limiting
The high-traffic API endpoints are protected by per-project token buckets stored in Redis. Each bucket has a sustained rate (`*_PER_SECOND`) and a burst ceiling (`*_BURST`) that absorbs spikes — useful for callers like real-time contact sync, which drains a backlog all at once and then idles.
Limits are keyed on the project rather than the IP address, so one customer's runaway integration cannot consume another's budget. Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`; a throttled request returns `429` with a `Retry-After` header. If Redis is unreachable, requests are allowed through rather than rejected.
Rate limiting is **off by default** — upgrading Plunk will never start refusing traffic your callers were already sending. Set `RATE_LIMIT_ENABLED=true` to switch it on; none of the other variables have any effect until you do. Once enabled, set an individual `*_PER_SECOND` to `0` to disable a single bucket while leaving the others active.
| Variable | Required | Description | Default |
| ------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- | ------- |
| `RATE_LIMIT_ENABLED` | No | Master switch for all API rate limiting. Turn on when exposed to untrusted API clients. | `false` |
| `RATE_LIMIT_TRACK_PER_SECOND` | No | Sustained requests per second for `POST /v1/track`, usually the highest-volume endpoint. | `100` |
| `RATE_LIMIT_TRACK_BURST` | No | Burst ceiling for `POST /v1/track`. | `200` |
| `RATE_LIMIT_SEND_PER_SECOND` | No | Sustained requests per second for `POST /v1/send`. Also bounded by the project's billing limit. | `20` |
| `RATE_LIMIT_SEND_BURST` | No | Burst ceiling for `POST /v1/send`. | `50` |
| `RATE_LIMIT_CONTACTS_PER_SECOND`| No | Sustained requests per second across contact writes (`POST`, `PATCH`, `DELETE` on `/contacts`). | `50` |
| `RATE_LIMIT_CONTACTS_BURST` | No | Burst ceiling shared by those contact writes. | `100` |
Contact writes share one budget because a sync integration drives create, update and delete from the same upstream change feed — separate budgets would let a single runaway sync spend three times the intended allowance.
## Idempotency
Callers can pass an `Idempotency-Key` header to `POST /v1/track` and `POST /v1/send` to guarantee the request runs at most once. See [Idempotency](/guides/idempotency).
| Variable | Required | Description | Default |
| -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `IDEMPOTENCY_KEY_TTL_HOURS` | No | How long a used key stays claimed before it can be reused. Expired keys are swept hourly, so raising this grows the `idempotency_keys` table proportionally. | `24` |
## SMTP Server
The optional SMTP relay lets you send emails through Plunk via the SMTP protocol.
| Variable | Required | Description | Default |
| ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `SMTP_DOMAIN` | No | SMTP relay domain. Required when using Traefik's `acme.json` with multiple certificates so the correct cert can be selected. | `localhost` |
| `SMTP_ENABLED` | No | Explicitly enable SMTP features in the UI. Automatically enabled when `SMTP_DOMAIN` is set to a non-localhost value in production. | `false` |
| `PORT_SECURE` | No | SMTPS port (implicit TLS). | `465` |
| `PORT_SUBMISSION` | No | SMTP submission port (STARTTLS). | `587` |
| `MAX_RECIPIENTS` | No | Maximum number of recipients per email. | `5` |
## OAuth
Enables social login. Register an OAuth app with each provider and add the credentials here.
| Variable | Required | Description |
| --------------------- | -------- | ------------------------------- |
| `GITHUB_OAUTH_CLIENT` | No | GitHub OAuth app client ID. |
| `GITHUB_OAUTH_SECRET` | No | GitHub OAuth app client secret. |
| `GOOGLE_OAUTH_CLIENT` | No | Google OAuth app client ID. |
| `GOOGLE_OAUTH_SECRET` | No | Google OAuth app client secret. |
## Stripe
Required if you want to enable billing features. All Stripe variables must be set together for billing to activate.
| Variable | Required | Description |
| -------------------------- | -------- | --------------------------------------------------- | ------------------ |
| `STRIPE_SK` | No | Stripe secret key. |
| `STRIPE_WEBHOOK_SECRET` | No | Stripe webhook signing secret for verifying events. |
| `STRIPE_PRICE_EMAIL_USAGE` | No | Stripe price ID for metered pay-per-email usage. |
| `STRIPE_METER_EVENT_NAME` | No | Stripe meter event name. | `emails` (default) |
Checkout collects nothing upfront. Right after it completes, Plunk places a single charge of 2.00 (in the customer's billing currency) to confirm the card accepts off-session, merchant-initiated payments. This charge is created directly rather than from a price ID, so there's no variable for it. It's credited back to the customer's Stripe balance once verification succeeds. The same check runs whenever the customer changes their default card, which requires the `customer.updated` and `customer.subscription.updated` events on your Stripe webhook endpoint. See [Billing](/concepts/billing) for the customer-facing description.
`STRIPE_PRICE_ONBOARDING` has been removed. The separate one-time onboarding fee no longer exists, so you can delete the variable from your environment; it's ignored if still set.
If you use a Stripe Radar rule to request 3D Secure, exclude off-session payments from it
(`and not :is_off_session:`). The verification charge runs with no cardholder present, so a 3DS request it
cannot satisfy will leave every verification unresolved.
## Platform Emails
When configured, Plunk will send email notifications to users for critical events (e.g. project disabled, billing limits reached). Without these, only ntfy notifications are sent.
| Variable | Required | Description | Example |
| -------------------- | -------- | ---------------------------------------------------------- | ------------------------ |
| `PLUNK_API_KEY` | No | API key for a Plunk instance to send transactional emails. | `pk_...` |
| `PLUNK_FROM_ADDRESS` | No | From address used for platform notification emails. | `noreply@yourdomain.com` |
## Notifications (ntfy)
Plunk bundles a self-hosted [ntfy](https://ntfy.sh) server for internal system notifications.
| Variable | Required | Description | Default |
| ----------- | -------- | ----------------------------------------------------------------------------------- | --------------------------------- |
| `NTFY_PORT` | No | Port for the ntfy web UI (Docker Compose only). | `8080` |
| `NTFY_URL` | No | ntfy topic URL. Change this to use an external ntfy.sh server or your own instance. | `http://ntfy/plunk-notifications` |
## User Management
| Variable | Required | Description | Default |
| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------- | ------- |
| `DISABLE_SIGNUPS` | No | When `true`, the signup endpoint rejects new registrations. Useful for private instances. | `false` |
| `VERIFY_EMAIL_ON_SIGNUP` | No | When `true`, validates emails on signup — checks for disposable domains, plus-addressing, domain existence, and MX records. | `false` |
## Interface
| Variable | Required | Description | Default |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `SHOW_SPONSOR` | No | When `true`, the dashboard navigation shows a **Sponsor** link to [GitHub Sponsors](https://github.com/sponsors/driaug). Set to `false` to hide it. | `true` |
## Security
| Variable | Required | Description | Default |
| ----------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `AUTO_PROJECT_DISABLE` | No | When `true`, projects are automatically suspended when bounce or complaint rate thresholds are exceeded. Set to `false` to manage project status manually. | `true` |
| `EMAIL_RATE_LIMIT_PER_SECOND` | No | Override the email sending rate limit. If not set, Plunk automatically fetches the quota from your AWS SES account. | — |
| `EMAIL_WORKER_CONCURRENCY` | No | Number of emails the worker processes in parallel. When unset, derived from the effective rate limit so a higher SES quota scales throughput automatically. | — |
| `EMAIL_WORKER_MAX_CONCURRENCY`| No | Upper bound applied to the auto-derived worker concurrency. Raise this only after sizing the Prisma connection pool accordingly. | `50` |
## Advanced
Variables for unusual deployments. The defaults work for the standard Docker Compose setup — only change these if you know you need to.
| Variable | Required | Description | Default |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------ | ------- |
| `NGINX_PORT` | No | Host port the bundled Nginx reverse proxy binds to. Override when port 80/443 is already in use on the host (e.g. running behind another reverse proxy that forwards to a different port). | `80` |
## Phishing Detection
Plunk can use AI to detect and block phishing emails before they're sent. Requires an [OpenRouter](https://openrouter.ai) API key.
| Variable | Required | Description | Default |
| -------------------------------- | -------- | ------------------------------------------------------------------------------------------------- | -------------------------- |
| `OPENROUTER_API_KEY` | No | OpenRouter API key. When set, enables AI-powered phishing detection. | — |
| `OPENROUTER_MODEL` | No | LLM model to use for content analysis. See [OpenRouter models](https://openrouter.ai/models). | `anthropic/claude-3-haiku` |
| `PHISHING_DETECTION_SAMPLE_RATE` | No | Percentage of emails to check (0.0-1.0). For example, `0.1` means 10% of emails are analyzed. | `0.1` (10%) |
| `PHISHING_CONFIDENCE_THRESHOLD` | No | Minimum confidence percentage (0-100) required to auto-disable a project from a single detection. | `95` |
| `PHISHING_CUMULATIVE_THRESHOLD` | No | Number of phishing detections within the time window required to auto-disable a project. | `3` |
| `PHISHING_CUMULATIVE_WINDOW_MS` | No | Time window in milliseconds for cumulative phishing tracking. | `3600000` (1 hour) |
**How it works:**
- A random sample of emails (controlled by `PHISHING_DETECTION_SAMPLE_RATE`) are analyzed by the LLM for phishing content.
- Projects are automatically disabled if **either**:
1. A single email is detected with confidence ≥ `PHISHING_CONFIDENCE_THRESHOLD`, **or**
2. `PHISHING_CUMULATIVE_THRESHOLD` or more emails are flagged within the `PHISHING_CUMULATIVE_WINDOW_MS` time window.
- Detection history is stored in Redis and shared across all worker instances.
---
### Apps Wiki Content Docs Self Hosting Introduction (`apps/wiki/content/docs/self-hosting/introduction.mdx`)
---
title: Self-Hosting
description: Run Plunk, the open-source platform for transactional email, campaigns and workflows, on your own servers with Docker and Amazon SES.
---
## Requirements
- Docker and Docker Compose
- AWS SES account (for sending emails)
- Domain name with subdomains for each service
## Quick Start
1. Download the [docker-compose.yml](https://raw.githubusercontent.com/useplunk/plunk/next/docker-compose.yml)
2. Create environment variables with your configuration (see [Environment Variables](/self-hosting/environment-variables))
3. Run `docker compose up -d`
## Domain Setup
Configure these subdomains pointing to your server:
| Subdomain | Service |
|-----------|---------|
| `app.yourdomain.com` | Dashboard |
| `api.yourdomain.com` | API |
| `docs.yourdomain.com` | Documentation |
| `www.yourdomain.com` | Landing page |
| `smtp.yourdomain.com` | SMTP relay (optional) |
## Next Steps
- [Docker Deployment](/self-hosting/docker) — Configuration details
- [Environment Variables](/self-hosting/environment-variables) — All settings
- [AWS SES Setup](/self-hosting/email-setup) — Email configuration
---
### Apps Wiki Content Docs Self Hosting Meta.Json (`apps/wiki/content/docs/self-hosting/meta.json`)
{
"title": "Self-Hosting",
"pages": ["introduction", "docker", "environment-variables", "email-setup"]
}
---
--- METRICS ---
- Files Extracted: 42
- Estimated Token Budget: ~70633 tokens
- Canonical Reference: https://codewiki.google/github.com/useplunk/plunk
