# Lumail.io
> The AI-native email platform for newsletters, automations, and transactional email.
Full markdown concatenation of every published docs page.
# Documentation
Source: https://lumail.io/docs.md
Lumail is email marketing for creators and small teams. Start with how the product works. Use [Guides](/docs/guides) when you want a path, or [API Reference](/docs/api-reference/v2) when you want endpoints.
---
# SMTP
Source: https://lumail.io/docs/smtp.md
Use Lumail SMTP when an application can only send through SMTP and cannot call `POST /api/v1/emails` directly.
The endpoint is designed for low-volume transactional email: authentication codes, magic links, password resets, account invitations, receipts, and operational notifications. SMTP messages are accepted by the Lumail SMTP adapter, authenticated with a Lumail API token, then queued through the transactional priority lane.
## Connection Settings
| Setting | Value |
| -------- | -------------------------------------- |
| Host | `smtp.lumail.io` |
| Port | `587` |
| Security | STARTTLS |
| Username | Your organization slug, or any label |
| Password | A Lumail API token |
| From | An address on a verified Lumail domain |
The password is not your Lumail account password. Create an API token from **Settings -> API Tokens** and store it in your application's secret manager.
## Setup Checklist
1. Verify the sending domain in Lumail.
2. Create a Lumail API token in the same organization.
3. Configure your app to use `smtp.lumail.io` on port `587` with STARTTLS.
4. Use a `From` address on the verified domain.
5. Send one test email before enabling the integration in production.
> **Test-mode recipients.** Fixture addresses such as `user@example.com` never send real email. See [Test-mode recipients](/docs/api-reference/test-mode).
>
> **Recipient rate guards.** The same real mailbox is capped at 5 sends / 10 minutes and 20 / 24 hours. See [Recipient rate guards](/docs/deliverability/recipient-rate-guards).
For the full setup flow, use the [SMTP transactional email tutorial](/docs/tutorials/smtp-transactional-emails).
## Supabase Auth
Supabase Auth custom SMTP can use these values:
```text
Host: smtp.lumail.io
Port: 587
Security: STARTTLS
Username: your-org-slug
Password: lum_your_api_token
Sender email: auth@your-verified-domain.com
```
If your application supports HTTP hooks, prefer [POST /api/v1/emails](/docs/api-reference/api-emails-send). The HTTP API returns structured errors and avoids SMTP/MIME parsing.
## Related Documentation
- [SMTP transactional email tutorial](/docs/tutorials/smtp-transactional-emails) - End-to-end setup for an organization
- [SMTP endpoint reference](/docs/api-reference/smtp) - Response codes, limits, and behavior
- [Create an API token](/docs/tutorials/create-api-token) - Generate the SMTP password
- [Email domains](/docs/domains/email-domains) - Verify the sender domain
---
# Survey Block Formats
Source: https://lumail.io/docs/survey.md
A survey block is a one-question poll inside the email. Recipients answer by
clicking. There is no form to load and no account to create. The editor preview
is the email: same stacking, same button size, same labels, same bordered card.
Open the slash menu (`/`) and pick **Survey**. Switch the style from the block
toolbar.
## Buttons
Full-width answers, stacked, left-aligned, all the same size. Use this for a
short list of choices.
## Yes / No
Two stacked answers. Same geometry as Buttons — Yes sits above No, both full
width. Switching to this style rewrites the first two answers as Yes / No and
keeps the rest saved if you switch back.
## Emoji
Same stacked buttons, with an emoji you pick printed in front of each label.
Only this style shows the emoji in the email.
## NPS
A fixed 0–10 scale, left-aligned with the question. The captions under 0 and 10
are yours; leave them blank to use the recipient's language.
## Block settings
Click the survey to open the toolbar.
| Setting | What it does | Default |
| ----------------- | ------------------------------------------------------------------------------------------------- | ------------- |
| **Style** | `Buttons`, `Yes / No`, `NPS`, `Emoji` | Buttons |
| **Comment** | Lets the recipient add a free-text note (up to 1000 characters) after they vote | Off |
| **Alignment** | `left`, `center`, `right` — moves the question and the NPS scale. Stacked answers stay full width | left |
| **Answer colors** | Button fill and label color | black / white |
| **Show if** | Hide the block unless the subscriber matches the tag conditions | always shown |
NPS only: two caption fields under the scale (`Not at all` / `Absolutely` in
the editor). Empty means "translate on the vote page". Max 60 characters each.
Cosmetic edits (colors, alignment, visibility) never mint a new survey version.
## Limits
| Thing | Limit |
| --------------- | ------------------------------------------------- |
| Answers | 2–8 (NPS is fixed at 0–10) |
| Question | 300 characters |
| Answer label | 120 characters |
| NPS captions | 60 characters each |
| Comment | 1000 characters |
| Merge fields | Not allowed in the question, answers, or captions |
| Inside a Repeat | Not allowed |
Answers land on the campaign's **Survey** tab, on each subscriber's timeline,
and in subscriber filters. A `subscriber.survey.answered` workflow trigger
fires on the first answer only.
Once a campaign is sent, its survey block is frozen. Duplicate the campaign to
ask a different question.
For filters, automations, the TipTap node, and the anti-bot vote path, see
[Surveys (reference)](/docs/features/surveys). Default NPS captions follow the
[organization language](/docs/features/language).
---
# GDPR in Lumail
Source: https://lumail.io/docs/legal/gdpr-in-lumail.md
_Last reviewed: 2026-09-24_
> **Contract and transfer requirements:** Organization owners and administrators can accept and download a DPA in **Settings → Configuration → Data Processing Agreement**. Version 2026-09-15.1 incorporates EU SCC Modules Two and Three, the UK ICO Addendum and Swiss adaptations. It does not promise EU-only processing or complete the Customer's transfer assessment.
This page describes the product and infrastructure as they operate today. It is intended to help customers perform their own assessment; it is not legal advice and is not a certification that a particular use of Lumail complies with GDPR or French ePrivacy rules.
## Roles and responsibility
For subscriber lists, campaigns, and transactional recipients, the Lumail customer normally determines the purpose and means of processing and is the data controller. Codelynx, LLC operates Lumail and processes that data to provide the Service.
Codelynx is a separate controller for account, billing, security, support, and its own website analytics data. Customers remain responsible for their notices, legal bases, consent records, email content, recipient selection, and responses to data-subject requests.
## Current data map
| Data or operation | Primary system | Current location |
| ------------------------------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Subscriber profiles, subscription state, campaigns, and core email events | Neon PostgreSQL | AWS eu-central-1, Frankfurt, Germany |
| Application and Redis runtime | netcup | Nuremberg, Germany |
| Email delivery and bounce or complaint feedback | Amazon SES | ap-southeast-2 (Sydney, Australia), eu-central-1 (Frankfurt, Germany) or us-west-1 (N. California, USA), depending on the region selected for each sending domain |
| Sent-email content archives | Cloudflare R2 | APAC placement; no EU-only jurisdiction guarantee |
| Transactional content and background-job orchestration | Hatchet | Self-hosted in Nuremberg, Germany |
| Queued message orchestration | Upstash QStash | EU service endpoint |
| Product analytics and application diagnostics | PostHog Cloud EU | Frankfurt, Germany |
| DNS, CDN, and security traffic | Cloudflare | Global edge network |
| Limited operational delivery-failure alerts | Discord | Global service; alerts may include a subscriber email address |
Opens, clicks, bounces, complaints, and unsubscribe events are stored in the same Frankfurt PostgreSQL region as subscriber records. This does not mean all related data stays there: SES, R2, Cloudflare, QStash, and operational alerts can process related data elsewhere. Hatchet job payloads are processed on the self-hosted German worker.
See the [Privacy Policy](/legal/privacy) for the complete public disclosure.
## International transfers
Codelynx does not currently claim certification under the EU-U.S. Data Privacy Framework. DPA version 2026-09-15.1 incorporates the European Commission's 2021 Standard Contractual Clauses for controller-to-processor and processor-to-subprocessor transfers, the UK ICO Addendum and Swiss adaptations.
Those clauses create a Customer-to-Codelynx transfer instrument. They do not replace the required assessment of the destination country's laws, supplementary measures where needed, or the upstream safeguards for each onward transfer. Infrastructure-provider DPAs and SCCs cover only the parties and transfers identified in those agreements.
See [Data Processing Agreement](/docs/legal/dpa) for the current contractual status.
## GDPR setup checklist
Before collecting subscribers, an EU customer should:
1. **Complete the required agreements.** Review and accept the current organization DPA. It supplies the applicable EU, UK and Swiss transfer terms between you and Codelynx, but you must still document the transfer assessment and any supplementary measures before starting the affected processing.
2. **Publish your own privacy notice.** Identify your purposes, legal bases, recipients, transfers, retention periods, and how subscribers can exercise their rights.
3. **Enable native double opt-in.** In **Settings → Configuration → Double Opt-In**, enable the setting before collecting subscribers when confirmation is appropriate for your legal basis and market. Step-by-step: [Enable Double Opt-In](/docs/tutorials/enable-double-opt-in).
4. **Minimize data.** Send only fields needed for the stated purpose. Do not place special-category or children's data in Lumail without a separate assessment and written agreement.
5. **Choose tracking deliberately.** Open pixels and tracked links can require notice or consent. Marketing campaigns, native double-opt-in confirmation emails, and transactional API, SDK, MCP, and SMTP sends track opens and clicks. Set `tracking.open` and `tracking.links` to `false` when tracking is not necessary or not lawful. Lumail account OTP and magic-link emails are sent without tracking.
6. **Keep independent consent evidence.** Store the notice version, source, timestamp, purpose, and consent wording in your own system. Native Lumail confirmation stores `confirmedAt` and `confirmationIp`, but those fields are not a complete consent record by themselves.
7. **Test rights handling.** Verify export, unsubscribe, suppression, and **lawful erasure** (not the disabled DELETE API) before launch. Contact [help@codelynx.dev](mailto:help@codelynx.dev) for downstream provider deletion.
## Native and custom double opt-in
Lumail's recommended flow is the native double opt-in. See [Enable Double Opt-In](/docs/tutorials/enable-double-opt-in) for the Configuration screenshots and the confirmation email editor.
1. Enable **Double Opt-In** in organization configuration.
2. Add the subscriber through the Subscribers API or a Lumail capture flow.
3. Lumail creates the subscriber as `PENDING_CONFIRMATION` and sends the native confirmation email.
4. The Lumail confirmation link changes the status to `SUBSCRIBED` and records the confirmation time and IP address.
The transactional email API behaves differently:
- It always creates a subscriber row when the address does not already exist.
- By default that row is `TRANSACTIONAL`: delivery, bounce, and complaint tracking without marketing eligibility.
- If **Settings → Configuration → Add transactional recipients to the marketing list** is on, the new row is `SUBSCRIBED` and a subscribed event is recorded. Double opt-in is ignored on this path.
- Existing contacts are reused and never have their status changed. `TRANSACTIONAL` becomes `SUBSCRIBED` only on a real subscribe (capture, import, admin, or API upsert with resubscribe).
- Adding a custom tag does not change `PENDING_CONFIRMATION` or `TRANSACTIONAL` to `SUBSCRIBED`, populate `confirmedAt`, or prove consent in Lumail.
Therefore, do not use the transactional API plus a confirmation tag as Lumail's custom double-opt-in mechanism. Use the native flow, or keep the entire consent and marketing-eligibility state in your own system and do not treat Lumail's `SUBSCRIBED` status as proof of consent. Transactional sends track opens and clicks unless you disable them:
```json
{
"transactional": true,
"tracking": {
"open": false,
"links": false
}
}
```
## Retention, deletion, and suppression
Lumail does not currently provide a contractually guaranteed retention period for every data category.
Ordinary subscriber `DELETE` is not a product operation: `DELETE /api/v1/subscribers/{id}` returns 405 and the `delete_subscriber` tool is disabled. Unsubscribe stops marketing mail and keeps history.
An authorized organization owner or admin can run **lawful erasure** from the subscriber detail page (confirm `ERASE`). That path:
- scrubs identifiable subscriber fields, email bodies, snapshots, clicks/opens, events, capture events, and related AI conversation mentions
- deletes R2 content objects whose keys are known
- writes a hashed tombstone so imports, API upserts, and transactional sends cannot recreate the address
- keeps hashed suppression / delivery-guard identities so the address is not emailed again
It does **not** automatically erase SES provider logs, PostHog events, historical import files, or database backups. Those exceptions are recorded on the erasure ledger. Contact [help@codelynx.dev](mailto:help@codelynx.dev) for downstream provider deletion. Do not promise a completion date for third-party stores without that follow-up.
The accepted DPA governs Codelynx's processing obligations; it does not imply an automated deletion deadline.
See [Customer compliance guide](/docs/legal/customer-compliance).
## Security and incident handling
Lumail uses TLS, access controls, separated environments, provider security controls, and abuse monitoring. These measures reduce risk but do not create an absolute security guarantee. Customers should limit API-token permissions, rotate credentials, use separate development and production tokens, and report suspected incidents to [help@codelynx.dev](mailto:help@codelynx.dev).
## Planned compliance work
The organization DPA can be accepted electronically and downloaded with its acceptance record. Maintaining the transfer assessment, upstream provider evidence and notification processes, and improving retention and downstream erasure controls remain distinct work. A signed DPA is not a certification of all product behavior or a completed transfer assessment.
---
# Data Processing Agreement (DPA)
Source: https://lumail.io/docs/legal/dpa.md
_Last reviewed: 2026-09-15_
Lumail provides an organization Data Processing Agreement (DPA) with **Codelynx, LLC**, 8 The Green STE B, Dover Delaware 19901, United States. It describes the parties' processing obligations, confidentiality, security, subprocessors, rights assistance, incidents, return and erasure, and audit arrangements.
## Review and accept
1. Open your organization's **Settings → Configuration → Data Processing Agreement**.
2. Read the agreement and confirm the organization's legal name and address.
3. Select whether the organization acts as a controller, a processor for its own client, or both for the transferred data.
4. Enter your full legal name, including your family name.
5. Check the express agreement and authority confirmation, then select **Sign agreement**.
Only an organization owner or administrator can sign on the organization's behalf. You must have authority to bind its legal entity. If your organization acts for a client, it must also have authority to appoint Codelynx as a further processor. A marketing opt-in or acceptance on behalf of your subscribers is not created by signing this contract.
## Download your agreement
After signing, use **Download signed PDF** to receive the contract with the recorded parties, signer and acceptance details. Keep a copy for your records.
The accepted text is saved with its version and acceptance time. Changing an organization profile or publishing a new template does not rewrite an earlier agreement. Downloading an unsigned document does not constitute acceptance.
## International transfers and compliance scope
The DPA is an agreement about processing obligations. It is **not**:
- An EU-only hosting or data-residency commitment.
- A Data Privacy Framework or security certification.
- A completed transfer impact assessment.
Version 2026-09-15.1 incorporates the European Commission's 2021 Standard Contractual Clauses by reference: Module Two for controller-to-processor transfers and Module Three for processor-to-subprocessor transfers. The Customer selects its applicable role or roles when signing. The DPA also incorporates the UK ICO transfer addendum and Swiss adaptations. Accepting that DPA electronically signs the selected transfer terms between the Customer and Codelynx.
The clauses do not remove the need to assess the destination country's laws, document the transfer assessment, apply any necessary supplementary measures, and verify the safeguards used for onward transfers. If those requirements cannot be met, the affected transfer must be suspended or stopped. Provider agreements do not replace the Customer-to-Codelynx clauses.
The Customer remains responsible for its lawful purposes, notices, recipient selection and tracking choices. See [GDPR in Lumail](/docs/legal/gdpr-in-lumail) and the [Privacy Policy](/legal/privacy) for the disclosed configuration and limitations.
## Rights, erasure and contract questions
Contact [help@codelynx.dev](mailto:help@codelynx.dev) for data-subject assistance, authorized erasure or return, provider information, audit requests and transfer requirements. Ordinary unsubscribe preserves data and is not an erasure request. The scope and completion arrangements must account for archives, snapshots, queues, logs, backups and applicable exceptions.
The accepted DPA contains the binding terms for the signing organization. This explanatory page does not replace that contract or constitute a compliance certification.
---
# Subprocessors
Source: https://lumail.io/docs/legal/subprocessors.md
_Last reviewed: 2026-09-24_
This register describes processors Codelynx uses to operate Lumail. It is an operational disclosure, not a Data Processing Agreement. See [DPA status](/docs/legal/dpa).
Locations are configured or typical processing locations. Edge networks, support access, and provider backups may involve additional countries. Unverified facts are marked unknown.
## Current register
Hashed suppression and delivery-guard records are retained by Lumail after unsubscribe or lawful erasure so the same address is not emailed again.
## Self-hosted vs external
Hatchet and the Lumail application process are self-hosted on netcup. They are not separate legal subprocessors. Neon, AWS, Cloudflare, Upstash, PostHog, Stripe, Discord, Google, OpenAI, and Tchao are external services when used.
## Change procedure
Codelynx gives customers who accept the current DPA **at least 30 days' advance written notice** before adding or replacing a subprocessor, with an objection channel at [help@codelynx.dev](mailto:help@codelynx.dev). The notice describes the provider, processing and intended start date. Customers who have not accepted the DPA should not treat the public list alone as a contractual notification mechanism.
This page will be updated when the register changes. Archived prior versions are the git history of this file until a dedicated archive is published.
---
# Security and incident contact
Source: https://lumail.io/docs/legal/security.md
_Last reviewed: 2026-09-15_
This page describes how to reach Codelynx about security and personal-data incidents. It does not claim ISO, SOC, or other certifications. Organization owners and administrators can accept and download the current [Data Processing Agreement](/docs/legal/dpa).
## Contacts
| Purpose | Address |
| ---------------------------------------------------- | ---------------------------------------------------------------------- |
| Privacy, DSAR follow-up, incident notice to Codelynx | [help@codelynx.dev](mailto:help@codelynx.dev) |
| Product support | [contact@lumail.io](mailto:contact@lumail.io) |
| Operator | Codelynx, LLC, 8 The Green STE B, Dover, Delaware 19901, United States |
## Vulnerability reports
Email [help@codelynx.dev](mailto:help@codelynx.dev) with a description, affected URL or API, and reproduction notes. Do not include secrets or customer personal data beyond the minimum needed to demonstrate the issue. We do not operate a paid bug-bounty program.
## Customer incident updates
If Codelynx confirms a personal-data incident that affects subscriber or account data we process for a customer, we aim to notify that customer's organization **without undue delay** after confirmation. That processor-to-controller notice is separate from the customer's own deadline to notify a supervisory authority or data subjects.
We do not promise a fixed 72-hour customer SLA on this page. Statutory controller deadlines are the customer's obligation.
## Measures we actually operate
Documented, evidenced controls — not certifications:
- TLS in transit for the application and APIs
- Organization-scoped data access and API tokens with permissions
- Separate development and production environments
- Passwordless email OTP for Lumail accounts (OTP mail is untracked)
- Sent-email archives stored in Cloudflare R2; lawful erasure deletes known object keys
- Hatchet workers self-hosted in Nuremberg; Postgres in Frankfurt
- Bounce, complaint, and unsubscribe suppression to stop further sending
No service is completely secure. We cannot guarantee that unauthorized access, loss, or disclosure will never occur.
## What to do as a customer
1. Limit API-token permissions and rotate tokens after staff changes.
2. Use separate development and production tokens.
3. Enable native double opt-in before collecting marketing subscribers when that is appropriate for your market.
4. Leave transactional tracking off unless you have a documented reason to enable it.
5. Use lawful erasure for data-subject deletion; do not promise the disabled `DELETE` subscriber API.
6. Report suspected incidents to [help@codelynx.dev](mailto:help@codelynx.dev).
---
# Customer compliance guide
Source: https://lumail.io/docs/legal/customer-compliance.md
_Last reviewed: 2026-09-24_
This guide helps customers assess Lumail. It is not legal advice and not a certification that a particular use complies with GDPR, UK GDPR, Swiss FADP, or ePrivacy rules. Suggested notice wording below is for adaptation only.
## 1. Can you sign a DPA today?
**Yes.** An organization owner or administrator can accept and download the current Article 28 DPA in **Settings → Configuration → Data Processing Agreement**. Version 2026-09-15.1 also incorporates EU SCC Modules Two and Three, the UK ICO Addendum and Swiss adaptations. Lumail does not claim DPF certification or EU-only residency, and the Customer must still complete its transfer assessment and any necessary supplementary measures.
## 2. Who is controller vs processor
You normally determine why subscriber and campaign data is processed and are the controller (or a processor for your own client). Codelynx processes that data to provide Lumail. Codelynx is a separate controller for account, billing, security, support, and its own website analytics.
Your Article 6 lawful basis remains your obligation. Signing the DPA does not establish subscriber consent or make every processing purpose lawful.
## 3. Data map
See the table in [GDPR in Lumail](/docs/legal/gdpr-in-lumail) and the [subprocessor register](/docs/legal/subprocessors). Current configured locations:
- Postgres: Frankfurt
- App + Hatchet: Nuremberg
- SES: Sydney (ap-southeast-2), Frankfurt (eu-central-1) or N. California (us-west-1), depending on the region selected for each sending domain
- R2 archives: APAC, no EU-only jurisdiction
- QStash: EU endpoint
- PostHog: EU cloud
A location hint is not a residency guarantee.
## 4. Tracking vs marketing consent
These are independent choices:
| Flow | Tracking default | Marketing eligibility |
| --------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Campaign / newsletter send | Open + click **on** | Existing `SUBSCRIBED` audience |
| Transactional API / SDK / MCP / SMTP | Open + click **on** (set both to `false` to disable) | New addresses become `TRANSACTIONAL` unless you enable "add transactional recipients to the marketing list" |
| Native double opt-in confirmation | Open + click **on** | Pending until the recipient confirms |
| Lumail account OTP | **Off** | Not marketing consent |
Account creation and an OTP do not establish marketing consent. Enable native DOI in **Settings → Configuration → Double Opt-In** before collecting marketing subscribers when confirmation is appropriate.
Suggested customer notice fragment (adapt, do not copy blindly):
> We send you product and account email you requested. Newsletter and promotional email is sent only if you subscribed and, where required, confirmed. Open and click measurement uses a tracking pixel and rewritten links on campaigns, confirmation emails, and transactional mail. Lumail account sign-in codes are not tracked.
## 5. Export and correction
- List export: organization subscriber export (CSV, 7-day file retention).
- Single contact: dashboard, `get_subscriber`, and related events/emails APIs.
- Correction: PATCH / dashboard update. Email address is immutable on an existing row; create a new contact only if that is lawful.
There is no dedicated single-subject DSAR API beyond those tools.
## 6. Unsubscribe vs lawful erasure
| Action | Who | Effect |
| --------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------ |
| Unsubscribe | Recipient link, API, dashboard | Stops marketing mail; row and history remain |
| `DELETE /api/v1/subscribers/{id}` | API | **405** — disabled |
| Lawful erasure | Organization owner/admin, confirm `ERASE` | Scrubs identifiable data, deletes known archives, tombstones the address |
Use erasure for a data-subject deletion request. It keeps hashed suppression so you do not email the address again. SES, PostHog, backups, and old import files are recorded exceptions — email [help@codelynx.dev](mailto:help@codelynx.dev) if those stores must be chased.
Do not re-import an erased address. The API returns `SUBSCRIBER_ERASED`.
## 7. Your responsibilities
- Publish your own privacy notice and choose legal bases.
- Keep independent consent evidence (notice version, source, timestamp, wording). Lumail `confirmedAt` / `confirmationIp` are not a complete consent record.
- Do not place special-category or children's data in Lumail without a separate assessment.
- Honor objection and unsubscribe without using Lumail history as a reason to keep emailing.
- Do not treat chatbot or docs answers as legal authority.
## 8. Procurement pack
The current procurement pack is: your downloaded signed DPA, this guide, [DPA details](/docs/legal/dpa), [subprocessors](/docs/legal/subprocessors), [security](/docs/legal/security), [privacy](/legal/privacy), and [terms](/legal/terms). Keep your own transfer assessment and evidence for any supplementary measures with that pack. Contact [help@codelynx.dev](mailto:help@codelynx.dev) for provider information or audit requests.
---
# Choose an Email MCP for Claude Code, Then Ship the Launch
Source: https://lumail.io/docs/playbooks/email-mcp-claude-code-product-launch.md
The best email MCP for Claude Code is the one that can complete your actual launch workflow with clear authentication, observable drafts, audience controls, and a deliberate delivery boundary. Lumail fits when you want Claude Code to operate campaigns, subscribers, workflows, and analytics while keeping consequential delivery behind an explicit approval path.
The goal is not to talk about an email platform. The goal is to ship a product change and let your owned list sell it while you keep building.
## What “best email MCP” should mean
Do not choose an MCP by its tool count alone. Test one real release against these criteria:
| Criterion | Question to ask |
| ----------------- | ----------------------------------------------------------------------------- |
| Authentication | Is access tied to the correct account or organization, and can it be revoked? |
| Campaign state | Can the agent create a saved draft that a human can open and edit? |
| Audience evidence | Can it show the saved audience rule and recipient estimate? |
| Final rendering | Can it inspect the email with variables, links, and footer resolved? |
| Delivery boundary | Is scheduling or sending separated from drafting and review? |
| Reporting | Can it read the result back into the same release conversation? |
| Pricing fit | Does the billing model match list size and sending frequency? |
A polished writing assistant fails this test if it leaves you copying text between tools. A broad MCP can also fail if it hides the exact audience or makes delivery too easy to trigger accidentally.
## Lumail and Kit both have email MCPs
As of August 14, 2026, this is no longer a category with one provider. Kit documents a 65-plus-tool MCP for paid plans, including Cursor and Claude clients. Lumail exposes an organization-aware tool catalog through MCP, with different safety profiles for OAuth plugins and API-token connections.
| Decision | Lumail | Kit |
| --------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Best fit | Programmable campaigns, graph workflows, transactional email, and send-volume pricing | Creator newsletters, commerce, recommendations, and subscriber-tier pricing |
| Claude Code path | OAuth plugin with read and safe draft-write tools; full CLI beside it | Remote OAuth MCP on paid Kit plans |
| Delivery boundary | OAuth plugin does not expose send or schedule; use the app or CLI | Open-world actions return a Kit confirmation link |
| Pricing basis | Emails delivered; subscribers are unlimited on every plan | Active-subscriber tier on paid plans |
| Current catalog claim | 89 organization-scoped tools across the full catalog | 65-plus MCP tools in Kit's current help documentation |
Read the [full Lumail versus Kit comparison](/posts/lumail-vs-kit) and Kit's [official MCP guide](https://help.kit.com/en/articles/14827557-how-to-connect-the-kit-mcp-to-your-ai-tools) before buying. Features and prices change; the practical benchmark is one representative launch, not the table alone.
## Connect Lumail to Claude Code
The Lumail plugin installs an OAuth MCP connection plus skills that teach Claude Code the workflow. Paste this into Claude Code:
Claude Code runs the marketplace commands, opens the browser sign-in, and verifies the connection. You must approve the organization in the browser.
Open a new Claude Code conversation after installation. Claude Code captures its MCP tool list when a session starts, so the conversation that installed the plugin cannot use newly added tools.
For the manual commands, scope details, removal instructions, and troubleshooting, use the canonical [Claude Code plugin guide](/docs/ai-integration/mcp-claude). Anthropic's [official MCP documentation](https://docs.anthropic.com/en/docs/mcp) explains the protocol from the client side.
## Turn a release into a launch campaign
### 1. Give Claude Code the release evidence
Point it at the changelog, product page copy, approved price, screenshots, and the exact checkout URL. Tell it which source wins when facts conflict.
Use a bounded request:
### 2. Make the reader's result the story
Lead with the work the release removes or the result it unlocks. The stack can appear in one short proof section:
`release evidence → Claude Code → Lumail draft → human review → owned list → offer`
Lumail is the campaign layer. It should not replace the customer's problem, the product proof, or the offer in the narrative.
### 3. Inspect the saved state
Ask Claude Code to read the campaign back. Verify the ID, subject, sender, audience, and every unsupported claim it found. Then open the same draft in Lumail's visual editor for final copy and layout changes.
### 4. Review the rendered email
Ask for the final HTML or text render with variables and the unsubscribe footer resolved. Check links against the production destinations. Repository URLs, preview deployments, and an HTTP 200 are not proof that checkout or onboarding works for a real buyer.
### 5. Deliver through the approved surface
The OAuth plugin intentionally does not register send, schedule, publish, unsubscribe, or delete tools. Finish in the Lumail app, or use the full CLI in your terminal after an explicit send request:
```bash
npx lumail auth login
```
This boundary lets Claude Code prepare nearly all the work without silently converting “draft this” into “contact my list.”
### 6. Bring the result back to the release
After delivery, ask for campaign delivery, clicks, and conversion events, then add the useful result to the next release brief. Do not treat an open rate as revenue. Compare the call-to-action click and purchase path with a similar audience and offer.
## Can Claude Code send a newsletter?
Claude Code can prepare and inspect a Lumail newsletter through the OAuth plugin, but that connection does not expose send or schedule tools. Final delivery happens in the Lumail app or through the Lumail CLI after explicit approval. This separation keeps the draft workflow agent-friendly while preserving a visible human decision before the list is contacted.
## Start from the source-of-truth prompts
The seven-prompt pack already covers the recurring jobs behind this launch: turn a changelog into an issue, rank subject lines, segment clickers, review results, and build the follow-up sequence.
[Get the seven prompts that run a newsletter](/?prompts=1), then use the [Ship with Email hub](/docs/playbooks) for the complete operating loop.
---
# Send a Newsletter from Cursor, Then Ship the Launch
Source: https://lumail.io/docs/playbooks/send-newsletter-from-cursor.md
You can send a newsletter from Cursor by connecting an email MCP, creating a saved campaign from the files already open in your workspace, reviewing its audience and rendered output, and explicitly confirming delivery. With Lumail's API-token MCP, Cursor can work against the same organization data as the dashboard instead of returning copy you must paste into another tool.
The launch remains the story. Cursor is where the evidence lives, and Lumail is the email line in the stack.
## What you need before Cursor writes anything
- a Lumail organization with a verified sending domain and sender;
- a consented subscriber list or a controlled test segment;
- a current API token stored outside the repository;
- the release notes, offer, price, and destination URL;
- one campaign goal and one call to action.
Do not ask Cursor to infer production claims from code. Tell it which files are approved source material and which facts need a live check.
## Connect Cursor to Lumail
The shortest setup is to paste this into Cursor Agent:
The machine-readable install guide selects the supported transport, configures the client, and verifies the live tool list. The manual API-token configuration and stdio fallback live in the canonical [Cursor MCP guide](/docs/ai-integration/mcp-cursor).
Cursor's [official MCP documentation](https://docs.cursor.com/context/model-context-protocol) describes remote transports, project and global configuration, tool approvals, and how Agent uses enabled MCP tools. Keep secrets out of project-level files that could be committed.
## The launch workflow inside Cursor
### 1. Extract a campaign brief from the release
Ask Cursor to produce a five-line brief before it calls any email tool:
1. the audience;
2. the change that matters to them;
3. the proof available in the workspace;
4. the offer or next action;
5. missing facts that block the campaign.
Resolve the missing facts. A generated paragraph is not a substitute for a confirmed price, deadline, or feature state.
### 2. Create a draft, not a send
Use a request that makes the boundary explicit:
The campaign ID is the handoff between the conversation and the dashboard. Read the same object back before moving on.
### 3. Make the email about the shipped result
Use this sequence:
`old friction → shipped change → concrete proof → one action`
Avoid turning the body into release-note bullets. Show how the release changes the reader's work, then link to the live result. Lumail only needs one line when the stack itself is relevant.
### 4. Render for a real test subscriber
Ask Cursor to render the saved draft with a controlled subscriber so variables and conditional content resolve. Check:
| Check | Evidence to read back |
| ------------ | ----------------------------------------- |
| Identity | Campaign ID and draft status |
| Sender | From and reply-to addresses |
| Audience | Saved filter and recipient estimate |
| Content | Subject, preview, HTML, and text |
| Safety | Unsubscribe link and unresolved variables |
| Destinations | Final URLs, not development links |
If the render differs from the chat draft, the render wins. It is closer to what the recipient receives.
### 5. Send a test and review it in an inbox
Request a test only after the draft read-back is correct. Open it on desktop and mobile, click every destination, and verify the sender identity. A successful test tool call proves the test was accepted, not that the production campaign is ready.
### 6. Confirm the final schedule
Lumail marks campaign scheduling as a dangerous action because it delivers to every matching recipient and cannot be undone after sending. Over the API-token MCP, the first scheduling call returns a short confirmation challenge. Approve the exact campaign, audience, date, time, and time zone before Cursor repeats the call with that confirmation.
Use this final read-back:
### 7. Read the launch result in the same workspace
After delivery, bring campaign performance back beside the release notes. Compare clicks and purchase events with previous campaigns to a similar audience. Record one change for the next launch rather than rewriting the whole system from one send.
## Can Cursor send a newsletter directly?
Yes. Cursor can use Lumail's API-token MCP to draft, render, test, and schedule a campaign when those tools are enabled for the organization. Scheduling requires explicit confirmation because it contacts real recipients. If you use a reduced OAuth connection instead, complete delivery in the Lumail app or with the CLI according to that connection's exposed tools.
## Keep the prompt system stable
Use the existing pack instead of creating a new prompt library for Cursor. It includes the changelog-to-issue prompt, click-based segmentation, subject-line ranking, re-engagement, reporting, and welcome-sequence jobs used in this workflow.
[Get the seven prompts that run a newsletter](/?prompts=1), or return to the [Ship with Email hub](/docs/playbooks).
---
# Move a Launch List from Kit Without Paying for Dormant Subscribers
Source: https://lumail.io/docs/playbooks/move-launch-list-from-kit.md
If your list is large but you contact only a focused segment each month, a Kit alternative that prices by emails sent can fit better than subscriber-tier billing. Lumail stores unlimited subscribers on every plan and prices by email volume. The safe migration is not a full export on day one: move one representative launch, prove the audience and delivery workflow, and compare a normal month with a peak month.
This page is published by Lumail. Check both providers' current pricing and product documentation before deciding.
## The pricing model is the decision
Kit counts unique active subscribers for its plan tiers. Its free Newsletter plan currently supports up to 10,000 subscribers, while paid Creator starts at $33 per month billed annually for 1,000 subscribers. Kit's [official pricing page](https://kit.com/pricing) is the current source for those terms.
Lumail charges for email volume instead of stored subscriber count:
| Lumail plan | Included volume | Current base price |
| ----------- | ------------------------------------ | ------------------ |
| Free | 3,000 emails per month | $0 |
| Premium | 40,000 emails, then $0.60 per 1,000 | $20 per month |
| Business | 400,000 emails, then $0.40 per 1,000 | $200 per month |
Subscribers are unlimited on every Lumail plan. Verify the current terms on the [Lumail pricing page](/pricing).
## When send-volume pricing wins
Take a list of 50,000 stored subscribers and one monthly launch sent to a 10,000-person segment.
- Lumail prices the 10,000 delivered emails. The other 40,000 stored records do not change the plan.
- Kit prices the paid plan around the active subscriber tier, so the full active list affects the tier even when most people do not receive that launch.
Now invert the case. A 1,000-person list receiving a weekly newsletter sends roughly 4,500 emails per month. That exceeds Lumail's free allowance, while Kit's free Newsletter plan may cover the use case. Send-volume pricing is not universally cheaper; it favors a list that is large relative to monthly sends.
Model three states before moving:
1. a normal month;
2. the largest launch month from the last year;
3. the list size and send frequency you expect twelve months from now.
The [full Lumail versus Kit comparison](/posts/lumail-vs-kit) covers commerce, recommendations, MCP access, workflows, and transactional email alongside price.
## Kit now has an MCP too
Do not choose on outdated “AI-native versus no MCP” claims. Kit documents a 65-plus-tool OAuth MCP for paid plans that works with Cursor, Claude, ChatGPT, and other compatible clients. It can read account data, draft broadcasts, manage subscribers, and route consequential actions through confirmation in the Kit app.
Lumail's full catalog currently contains 89 organization-scoped tools. Its Claude Code OAuth plugin exposes read and safe draft-write operations, while the API-token MCP and CLI cover broader operations with confirmation controls.
Choose on the actual work:
| Need | Better question |
| ---------------- | ---------------------------------------------------------------------------- |
| Creator commerce | Do you need Kit's paid products and recommendation network? |
| Product email | Do newsletters, workflows, and transactional messages need one organization? |
| Agent access | Which client, tool scope, and confirmation model match the team? |
| Cost | Is list size or monthly delivered volume the stronger driver? |
## Migrate one launch before the whole list
### 1. Export complete consent state
Export active subscribers, unsubscribes, bounced addresses, complaints, tags, custom fields, and the source of consent. A migration that copies only active emails can accidentally make suppressed people contactable again.
### 2. Import a controlled segment
Start with internal addresses and a small consented segment that represents the real launch audience. Preserve the tags needed to recreate the campaign filter.
### 3. Authenticate the sending domain
Configure the required DNS records, verify the sender, and leave Kit live while records propagate. Do not move acquisition forms or active automations yet.
### 4. Rebuild one campaign and one automation
Choose the workflow that matters commercially: the launch campaign, welcome sequence, or buyer follow-up. Recreate its trigger, waits, branches, goal, and exit conditions. Test success, negative, and early-exit paths.
### 5. Run the same launch preflight
Read back the campaign ID, sender, audience rule, recipient count, links, unsubscribe state, and schedule. Send a test. Confirm delivery only after the rendered result matches the approved offer.
### 6. Compare operation as well as price
Measure:
- monthly cost in a normal and peak month;
- time from source material to approved draft;
- manual steps between agent, editor, and send;
- deliverability and complaint signals;
- clicks and attributed purchases;
- the time required to answer one subscriber-level support question.
Only then decide whether to move the remaining audience and automations.
## What Lumail does not replace
Lumail does not provide Kit's paid newsletter products, digital-product checkout, or recommendation network. If those drive audience growth or revenue, keep them in the stack or choose Kit. A lower email-platform bill is not a win if the migration removes the system that acquires or monetizes the audience.
## Use one prompt pack on either side of the migration
The same seven jobs remain: drafting, subject lines, click-based segments, re-engagement, changelog conversion, performance review, and a welcome sequence. Keep the prompts stable while changing the delivery system so the comparison is easier to interpret.
[Get the seven prompts that run a newsletter](/?prompts=1), then use the [Claude Code launch playbook](/docs/playbooks/email-mcp-claude-code-product-launch) or [Cursor newsletter playbook](/docs/playbooks/send-newsletter-from-cursor) for the first representative campaign.
---
# Ship with Email
Source: https://lumail.io/docs/playbooks.md
Your owned list sells while you ship when email is part of the release process, not a separate marketing project. The repeatable loop is simple: turn the change into a campaign, choose the people it helps, review the rendered email, deliver it with explicit approval, and feed the results into the next release.
Lumail is one line in that stack. Your product, checkout, source material, audience, and offer remain the system around it.
## Start with the result, not the email tool
The result is not “a newsletter was sent.” The result is that the right people understood what shipped and had one obvious next step.
Write these five facts before opening an editor:
| Decision | Example for a product launch |
| ---------------- | ------------------------------------------------------ |
| Commercial event | A paid feature is available today |
| Audience | Trial users who reached the relevant limit |
| Promise | Finish the task without the old workaround |
| Evidence | Release notes, screenshots, pricing, and the live page |
| One action | Upgrade or try the feature |
If the offer, proof, or audience is unclear, an agent only produces a faster vague campaign. Fix the launch brief first.
## Pick the playbook that matches the work
These pages share one operating model but answer different questions. Use one canonical guide for each job instead of copying the same setup across several pages.
### [Choose an email MCP for Claude Code, then ship the launch](/docs/playbooks/email-mcp-claude-code-product-launch)
Use this when the release work already lives in Claude Code. The guide covers what “best email MCP” should mean, how Lumail and Kit differ, and how to turn repository evidence into a reviewable campaign draft.
### [Send a newsletter from Cursor](/docs/playbooks/send-newsletter-from-cursor)
Use this when the brief, changelog, screenshots, and product code are already open in Cursor. The guide keeps drafting, rendering, audience review, confirmation, and reporting in one observable sequence.
### [Move a launch list from Kit without paying for dormant subscribers](/docs/playbooks/move-launch-list-from-kit)
Use this when subscriber-tier pricing no longer matches how often you contact the list. The guide moves one representative launch first, preserves suppression state, and compares a normal month with a peak month before a full migration.
## The six-stage shipping loop
### 1. Collect launch evidence
Give the agent primary material: the actual release notes, current pricing, screenshots, product page, and any claims already approved. A repository is useful evidence, but code alone does not prove that production works. Mark anything that still needs live verification.
### 2. Define the audience in plain language
“People likely to buy” is not a segment. “Active subscribers tagged `course-creator` who clicked a launch email in the last 90 days and have not purchased” is reviewable.
Ask for both the saved filter and the estimated recipient count. If either is surprising, stop before drafting.
### 3. Create a draft from the source material
The agent should return a campaign ID, subject, preview text, body, audience rule, and the facts it could not verify. Draft state is the right default because it is inspectable and reversible.
The product appears only where it explains the mechanism. A useful launch story is about what changed for the reader, how the release was promoted, and what happened next—not a feature inventory disguised as a tutorial.
### 4. Review the rendered email
Review what a recipient will receive, not only markdown in a chat. Check:
- sender and reply-to address;
- subject and preview text;
- personalization and conditional blocks;
- every link and button destination;
- unsubscribe behavior;
- mobile rendering;
- the exact recipient estimate.
The [campaign rendering workflow](/posts/ai-email-marketing-for-newsletters) explains why draft creation and final delivery should stay separate.
### 5. Approve delivery explicitly
Read back the campaign ID, sender, audience, recipient count, date, time, and time zone. A request to draft is never permission to send. A successful tool call is not proof of inbox delivery.
### 6. Close the loop with revenue evidence
Compare the launch with similar sends. Opens can expose subject-line or deliverability problems, but clicks and attributed purchases are closer to the commercial result. Record what changed, what remained constant, and what the next campaign will test.
## A citable answer to “how do I launch with email?”
To launch with email, define one audience and one action, build the campaign from verified release evidence, render and review the saved draft, approve the exact recipient set and schedule, then compare clicks and purchases with previous launches. Keep the email platform as one component in the shipping stack, not the story itself.
## Use the same seven prompts every week
Do not rebuild the operating system from scratch for every release. The existing prompt pack covers drafting, subject lines, click-based segments, re-engagement, changelog conversion, performance review, and a welcome sequence.
[Get the seven prompts that run a newsletter](/?prompts=1). It is the only prompt pack used throughout these playbooks.
## Related documentation
- [AI integrations and live tool categories](/docs/ai-integration)
- [Claude Code plugin setup](/docs/ai-integration/mcp-claude)
- [Cursor MCP setup](/docs/ai-integration/mcp-cursor)
- [Campaign and automation safety model](/posts/ai-email-marketing-for-newsletters)
- [Lumail pricing](/pricing)
---
# Guides
Source: https://lumail.io/docs/guides.md
Paths, not endpoint catalogs. For product concepts see [Documentation](/docs). For REST and the SDK see [API Reference](/docs/api-reference/v2).
## Start here
- [Create an API token](/docs/tutorials/create-api-token)
- [Send transactional email over SMTP](/docs/tutorials/smtp-transactional-emails)
- [React Email templates](/docs/tutorials/react-email)
- [Connect Claude or Cursor](/docs/ai-integration)
## Migrate
- [Migration to high deliverability emails](/docs/tutorials/migration-to-high-deliverability-emails) — branding, why-you-receive, double opt-in, and workflow timing
- [Migration to V2](/docs/api-reference/v2/migration) — rewrite a v1 REST or SDK integration to `/api/v2`
- [Move a launch list from Kit](/docs/playbooks/move-launch-list-from-kit)
- [Send a newsletter from Cursor](/docs/playbooks/send-newsletter-from-cursor)
- CLI: `npx lumail migrate import --file export.json` imports sending domains from a Lumail export. Contacts are not imported.
---
# Migration to high deliverability emails
Source: https://lumail.io/docs/tutorials/migration-to-high-deliverability-emails.md
Inbox placement is no longer "SPF + DKIM and hope". Gmail and Yahoo expect a recognizable sender and a sentence that explains why this specific person got this specific email — including one-time passwords and receipts. Lumail's editor scores those two things. This page is the migration path.
If you only need the confirmation switch, use [Enable Double Opt-In](/docs/tutorials/enable-double-opt-in). Come back here for branding, the why-line, OTP/transactional copy, and workflow timing.
If an AI agent is preparing the complete account, use [Prepare Your Lumail Account for Lumail 2.0.0](/docs/ai-integration/prepare-account-2-0). It includes the strict transactional-versus-marketing routing rule, Workflow draft sequence, and approval boundary.
## What "migrated" looks like
Every email that leaves the organization — campaign, workflow, confirmation, OTP, receipt — has:
1. **Visible branding** in the first screen of the body (logo, organization name, or your domain as its own first line).
2. **A why-you-receive sentence** in the same language as the email. Not the unsubscribe line.
3. **A real postal address** (`{{org-adresse}}` / `@org-adresse`) and an unsubscribe link on marketing mail.
4. **Native double opt-in** on public signups, with a branded confirmation email.
5. **Workflows that enroll `SUBSCRIBED` contacts**, not pending ones.
The content checker awards **5 points** for branding and **10 points** for the why-line. The default "Don't want to receive these emails?" footer does **not** count as a why-line. See [Content Deliverability Checker](/docs/features/content-deliverability).
## 1. Add clear branding
Put the brand where a human sees it without scrolling. The checker accepts any of:
- A **logo** block with a real image URL (filename-only or a hidden link does not count)
- The **organization name**, including the `{{org-name}}` / `@org-name` variable
- Your **domain alone** as the first text block (`melvynx.com`)
Snippets are checked too. Put the header (logo + name) in a snippet and reuse it in campaigns, workflow emails, and the confirmation template so the brand cannot drift.
Do this on OTP and transactional HTML as well. A bare "Your code is 482191" from `noreply@` with no logo and no product name looks like phishing. Same sender display name, same logo, same domain in the first lines.
## 2. Say why they received this email
Gmail/Yahoo want a causal sentence. Language does not matter. Shape does.
| Channel | Line that passes |
| --- | --- |
| Newsletter / campaign | `You're receiving this email because you signed up at example.com` |
| French list | `Tu reçois ce mail car tu t'es inscrit sur example.com` |
| Confirmation | `You're receiving this because you just signed up and need to confirm your email` |
| OTP / magic link | `You're receiving this because you requested a sign-in code for example.com` |
| Receipt / invoice | `You're receiving this because you placed an order on example.com` |
| Password reset | `You're receiving this because a password reset was requested for your example.com account` |
Write it in the email language. Put it near the footer, not only in preview text.
Does **not** count:
- `Don't want to receive these emails?`
- `Unsubscribe` alone
- A legal address with no causal phrase
Agents writing campaign/workflow bodies must add this sentence and visible branding. Call `get_skill({ type: "docs", page: "tutorials/migration-to-high-deliverability-emails" })` before rewriting a migrated list.
Transactional and SMTP sends (`html`, `markdown`, React Email) are not scored by the editor. Add the two lines yourself. Same rule as campaigns.
## 3. Turn on native double opt-in and brand the confirmation
Public capture pages, forms, and API signups should confirm the inbox before marketing starts.
**UI:** Settings → Configuration → **Double opt-in** → **Edit confirmation email**.
**Agent (admin/owner):**
```
get_organization_settings
update_organization_settings({ doubleOptInEnabled: true })
get_confirmation_email
update_confirmation_email({ subject, preview, template })
```
The confirmation body must include `{{confirmUrl}}` (button `url` or link `href`). Missing it is rejected. Use the same logo/name snippet and a why-line. Subject/preview should name the brand (`Confirm your Acme subscription`), not a generic "Confirm your email address" if you can do better.
What the switch does, and what it does not:
- New public signups become `PENDING_CONFIRMATION` and get one confirmation email (24h token).
- Existing `SUBSCRIBED` contacts stay subscribed. Enabling DOI is not a retroactive purge.
- Confirmation emails send from the organization's default sender.
- `skipDoubleOptIn: true` is for trusted backends (checkout, server sync) only. Never on a public form.
- `triggerWorkflows: false` skips the confirmation email. It is not a substitute for `skipDoubleOptIn`.
- Do not build a custom confirmation state machine with the transactional API.
Full source table: [Enable Double Opt-In](/docs/tutorials/enable-double-opt-in#what-uses-double-opt-in).
## 4. Set workflows up for confirmation
With DOI on, tag-triggered and "subscriber created" workflows **wait until the click**. Tags attached at signup are replayed after confirm so the welcome sequence enrolls a real `SUBSCRIBED` contact.
Do this:
1. `get_organization_settings` — if DOI is off and the list is public, turn it on first.
2. `get_skill({ type: "workflow" })` then `get_workflow` (keep `updatedAt`).
3. `configure_workflow_draft` with the full graph. EMAIL steps need complete inline content: branding, why-line, `{{unsubscribeUrl}}`, `{{org-adresse}}`.
4. Do not publish until the user confirms. `publish_workflow` is dangerous.
Do not:
- Enroll `PENDING_CONFIRMATION` contacts as if they were live.
- Put `skipDoubleOptIn` on a capture-page or client-side signup.
- Publish `subscriber.tag.added` with empty `tagIds`.
- Call `create_campaign` for a workflow email.
Manual enrollment (`add_subscribers_to_workflow`) still requires a subscribed contact. `dryRun: true` first.
## 5. Other current recommendations
These are the other recent product rules that belong in the same migration, not a second project:
| Item | Do |
| --- | --- |
| Physical address | `@org-adresse` in the footer. CAN-SPAM / inbox filters. |
| Unsubscribe | `{{unsubscribeUrl}}`. Type `/` → Unsubscribe Link. Translate the label if the email is not English. |
| No shorteners | `bit.ly`, `t.co`, and friends fail the checker. Use your own domain. Lumail already tracks clicks. |
| Tracking domain | Settings → Configuration → Tracking domains. Dedicated host for `/r/` tracked links, with DNS verification. Shared tracking is the fallback. |
| Sending subdomain | Prefer `mail.example.com` over the root. Isolate reputation. |
| Content checker | Fix the eleven checks before send. **Unspam** rewrites trigger words. |
| Transactional list | Keep **Add transactional recipients to the marketing list** off unless you have consent. OTP/receipt recipients must not become `SUBSCRIBED` by accident. |
| Trusted imports | CSV import writes `SUBSCRIBED` and does not send confirmation. Clean the file first. |
| Footer snippet | One branded footer (why-line + address + unsubscribe) reused everywhere. Settings → Language does not rewrite snippet copy. |
DNS, bounces, and DMARC stay on [Deliverability](/docs/deliverability) and [Email Domains](/docs/domains/email-domains). This page is content and consent, not SPF.
## Agent sequence
For a migration request ("make our emails high deliverability"):
1. `get_skill({ type: "docs", page: "tutorials/migration-to-high-deliverability-emails" })`
2. `get_writing_style` then `get_email_snippets` — reuse the header/footer if they exist, otherwise create them.
3. `get_organization_settings` → enable DOI if public signups are on.
4. Brand `update_confirmation_email` (must keep `{{confirmUrl}}`).
5. Rewrite campaign/workflow bodies with branding + why-line. `get_skill({ type: "campaign" })` / `get_skill({ type: "workflow" })` first.
6. For OTP/transactional templates in the customer's app, give them the two sentences to paste. `send_email` does not invent them.
Members can read settings and the confirmation template. Only owners/admins can flip DOI or save the confirmation email.
## Related documentation
- [Prepare Your Lumail Account for Lumail 2.0.0](/docs/ai-integration/prepare-account-2-0)
- [Enable Double Opt-In](/docs/tutorials/enable-double-opt-in)
- [Content Deliverability Checker](/docs/features/content-deliverability)
- [Account Verification](/docs/features/account-verification)
- [GDPR in Lumail](/docs/legal/gdpr-in-lumail)
- [Workflows](/docs/workflows)
- [Send React Email](/docs/tutorials/react-email)
- [Language](/docs/features/language)
---
# Clear Branding
Source: https://lumail.io/docs/tutorials/clear-branding.md
Clear branding answers one question immediately: **who sent this email?** A reader should not need to inspect the sender address, follow a link, or reach the unsubscribe footer to identify your business.
## Watch the walkthrough
This short walkthrough shows acceptable header and footer branding, what anonymous email looks like, and why the same identity should appear in every campaign.
If the player does not load, [watch the Clear Branding walkthrough on Tella](https://www.tella.tv/video/vid_cmttdso3f000a0agm5a9pa0g0/view).
## What clear branding means
Your email has clear branding when the visible content connects the message to a recognizable organization. Use at least one strong identifier:
- Your company or product name
- Your logo, with useful alt text
- Your website domain displayed as text
The sender name and address still matter, but they do not replace branding inside the email. Inbox interfaces can shorten or hide sender details, and forwarded emails can lose their original context.
## Put it in the header when possible
The header is the clearest place because readers see it before the message body. A simple logo and company name are enough.
**Good header example**
> **Acme**
> Weekly product notes from acme.com
In the Lumail editor, add a logo image or a first text block containing your organization name. You can type `@` and insert the **Organization name** variable so the name stays aligned with your settings.
Keep the header compact. Clear branding does not require a large banner, a slogan, or a navigation bar.
## Footer-only branding is acceptable
If a prominent header does not fit your personal or text-first style, identify the business in the footer. Include the company name, domain, or logo before the compliance links.
**Good footer example**
> Marie from Acme
> [acme.com](https://acme.com)
> 123 Main Street, Paris
> Unsubscribe (linked to `{{unsubscribeUrl}}`)
The footer must remain readable. Do not hide the identity in tiny, low-contrast text.
## Examples that work
| Email style | Clear branding |
| ---------------------- | ----------------------------------------------------------------------- |
| Product newsletter | Logo and **Acme** at the top |
| Personal founder email | “Marie from Acme” near the opening or signature |
| Plain-text update | “Acme — acme.com” in the signature |
| Promotional campaign | Consistent product name in the header and company details in the footer |
The design can change between campaigns. The identity should not.
## What does not work
These examples leave the reader guessing:
- “Hey, it’s Marie” with no company, product, domain, or logo
- A generic message signed only with a first name
- A logo used only as an image filename or hidden link destination
- A company name that appears only in the sender address
- Different brand names from one campaign to the next without explaining the relationship
If a subscriber cannot connect the email to the organization they recognize, the branding is not clear enough.
## Clear branding and reason for sending are different
Lumail checks these separately:
| Check | Question it answers | Example |
| ---------------------- | ---------------------- | ---------------------------------------------------------------- |
| **Clear branding** | Who sent this? | “Acme — acme.com” |
| **Reason for sending** | Why am I receiving it? | “You’re receiving this email because you signed up at acme.com.” |
Add both. Branding establishes identity; the reason-for-sending line reminds the reader how they joined your audience.
## Keep it consistent
Recognition grows through repetition. Once you choose a visible name, logo, and domain, reuse them across campaigns, workflows, and transactional messages.
Consistency helps readers recognize you faster and reduces the chance that a legitimate email feels unexpected. It supports trust and deliverability, but it does not replace sender authentication, consent, list hygiene, or an unsubscribe link.
## Check it in Lumail
1. Open your email in the editor.
2. Add a visible organization name, domain, or logo in the header or footer.
3. Open **Content checks** in the toolbar.
4. Confirm that **Branding** shows `5/5`.
5. Add a reason-for-sending sentence if that separate check is still missing.
The branding checker recognizes your organization name, the `@org-name` variable, a domain displayed in the first text block, or a logo image block. A hidden URL or image filename alone does not pass.
## Final checklist
- A new reader can identify the sender in a few seconds
- The company name, domain, or logo is visible in the email content
- The same identity appears across every email type
- The branding is readable on mobile and in dark mode
- The reason-for-sending line explains why the subscriber is on the list
- The footer also includes your physical address and unsubscribe link
## Related documentation
- [Reason for Sending](/docs/tutorials/reason-for-sending) — explain why the subscriber receives the email
- [Content Deliverability Checker](/docs/features/content-deliverability) — all eleven pre-flight checks
- [Migration to high deliverability emails](/docs/tutorials/migration-to-high-deliverability-emails) — branding, consent, and sending setup
- [Enable Double Opt-In](/docs/tutorials/enable-double-opt-in) — confirm subscriber ownership before campaigns
---
# Reason for Sending
Source: https://lumail.io/docs/tutorials/reason-for-sending.md
A reason-for-sending line answers the subscriber's question: **why am I receiving this email?** It connects the message to a real action they took, such as creating an account, joining a newsletter, downloading a resource, or buying a product.
## Watch the walkthrough
This two-minute walkthrough shows a clear account example, a version for multiple signup sources, and vague explanations that should be avoided.
If the player does not load, [watch the Reason for Sending walkthrough on Tella](https://www.tella.tv/video/vid_cmtte0eek00000agmhpiigfk5/view).
## Use action plus brand
The most reliable formula is:
> You're receiving this email because you **[action]** on or through **[brand or domain]**.
Both parts matter:
- **Action** reminds the subscriber what they did.
- **Brand or domain** gives them a name they can recognize and verify.
For example:
> You're receiving this email because you created an account on Lumail.io.
That sentence is specific enough for the reader to check whether they recognize Lumail and remember creating an account.
## Templates you can copy
Choose the template that matches the real source of the subscriber. Replace the example names and domains with your own.
| Source | Example reason |
| ------------------ | -------------------------------------------------------------------------------------- |
| Newsletter form | You're receiving this email because you subscribed to the Acme newsletter at acme.com. |
| Account creation | You're receiving this email because you created an Acme account. |
| Lead magnet | You're receiving this email because you downloaded the Email Checklist from acme.com. |
| Webinar | You're receiving this email because you registered for an Acme webinar. |
| Quiz or calculator | You're receiving this email because you used the pricing calculator on acme.com. |
| Purchase | You're receiving this email because you purchased an Acme product. |
| Waitlist | You're receiving this email because you joined the Acme product waitlist. |
The action does not need to be long. It needs to be true and recognizable.
## When subscribers come from multiple sources
You do not need a unique footer for every subscriber if several legitimate sources feed the same audience. Use a broader sentence that lists the real possibilities:
> You're receiving this email because you subscribed through acme.com, used one of our calculators, completed a quiz, or joined an Acme program.
Keep the list short and concrete. Do not include sources you do not use, and do not hide an unknown acquisition source behind a generic sentence.
If you know the exact source for each subscriber, segment the audience or use a custom field so the explanation can stay precise.
## Examples that do not work
These sentences repeat the obvious without explaining the original action:
- “You're receiving this email because you subscribed to my emails.”
- “You're receiving this email for marketing purposes.”
- “You're receiving this email because you gave me your email.”
- “You are on this list.”
They are also missing a recognizable company, product, or domain. Replace them with the actual signup event and the brand that collected the address.
## Reason for sending and clear branding are different
Lumail checks these separately:
| Check | Question it answers | Example |
| ---------------------- | ------------------------ | --------------------------------- |
| **Reason for sending** | Why am I receiving this? | “You created an account on Acme.” |
| **Clear branding** | Who sent this? | “Acme — acme.com” |
A strong reason-for-sending sentence often contains the brand, but the rest of the email should still be clearly branded. See [Clear Branding](/docs/tutorials/clear-branding) for header, footer, and consistency examples.
## Where to place it
Put the sentence in the footer, close to the unsubscribe link and your physical address. This keeps the explanation available without interrupting the main message.
A complete footer can look like this:
> You're receiving this email because you subscribed to the Acme newsletter at acme.com.
> Acme, 123 Main Street, Paris
> Unsubscribe: `{{unsubscribeUrl}}`
Use readable text and sufficient contrast. Do not hide the explanation in an image or make it difficult to find.
## Other languages
Write the reason in the same language as the email. Lumail recognizes common reason-for-sending patterns in English, French, Spanish, Italian, German, and Portuguese.
| Language | Example |
| -------- | -------------------------------------------------------------------- |
| English | You're receiving this email because you signed up at acme.com. |
| French | Tu reçois cet e-mail car tu t'es inscrit sur acme.com. |
| Spanish | Recibes este correo porque te registraste en acme.com. |
| German | Du erhältst diese E-Mail, weil du dich bei acme.com angemeldet hast. |
The exact wording can change. Preserve the action and the recognizable brand.
## Check it in Lumail
1. Open your email in the editor.
2. Add the reason-for-sending sentence to the footer.
3. Open **Content checks** in the toolbar.
4. Confirm that **Reason for sending** shows `10/10`.
5. Confirm separately that **Branding** shows `5/5`.
The default unsubscribe sentence — “Don't want to receive these emails?” — does not count because it does not explain how the subscriber joined.
## Final checklist
- The sentence describes a real subscriber action
- It names the company, product, channel, or domain they recognize
- Multiple sources are listed only when they genuinely feed the audience
- The wording matches the language of the email
- The sentence is visible near the unsubscribe link
- The email also contains clear branding, a physical address, and an unsubscribe link
This explanation improves recognition and reduces confusion, but it does not create consent by itself. Keep accurate signup records and only email people you are allowed to contact.
## Related documentation
- [Clear Branding](/docs/tutorials/clear-branding) — make the sender identifiable
- [Content Deliverability Checker](/docs/features/content-deliverability) — all eleven pre-flight checks
- [Enable Double Opt-In](/docs/tutorials/enable-double-opt-in) — confirm subscriber ownership before campaigns
- [Migration to high deliverability emails](/docs/tutorials/migration-to-high-deliverability-emails) — complete sending setup
---
# Enable Double Opt-In
Source: https://lumail.io/docs/tutorials/enable-double-opt-in.md
Double opt-in keeps people off your marketing list until they prove they own the inbox. The signup is the first opt-in. The confirmation click is the second.
Enable it before you collect subscribers in a market that expects consent evidence (France, the EEA, and most public capture pages). Lumail's native flow is the supported one — do not invent a custom confirmation state machine with the transactional API.
## Watch the complete walkthrough
This five-minute walkthrough shows the complete journey: enable the setting, customize the confirmation email, find a pending subscriber, confirm from the inbox, and see a post-confirmation workflow send.
If the player does not load, [watch the double opt-in walkthrough on Tella](https://www.tella.tv/video/vid_cmtqwcz0l00090agm7sxe8k8q/view).
## What it does
With **Enable Double Opt-In** on:
1. A new subscriber is created as `PENDING_CONFIRMATION`.
2. Lumail sends your confirmation email from the organization's default sender.
3. The subscriber clicks `{{confirmUrl}}`.
4. Their status becomes `SUBSCRIBED`. Lumail stores `confirmedAt` and `confirmationIp`, writes a subscribed timeline event, and starts tag-triggered workflows.
Until that click, they do not receive campaigns or workflow marketing emails. Filter **Subscribers → Pending Confirmation** to see who is waiting.
## How the confirmation works
```
Signup (form, API, capture page, integration)
↓
PENDING_CONFIRMATION + confirmation email (24h token)
↓
Click {{confirmUrl}} → /confirm?token=…
↓
SUBSCRIBED + confirmedAt / confirmationIp + workflows
```
The confirmation link is a single-use token URL. A second subscribe POST for the same pending address does not send a second email or rotate the token. If they never click, they stay pending — turning the setting off later does not subscribe them for you.
Existing `SUBSCRIBED` contacts are left alone when you enable the setting. Only **new** subscribers go pending.
## Enable it
1. Open **Settings → Configuration**. The URL is `/orgs/[your-org]/settings/configuration`.
2. Find the **Double Opt-In** card.
3. Turn **Enable Double Opt-In** on.
4. Click **Save**.
_The first card on Configuration. The switch is organization-wide._
| Control | What it does |
| --- | --- |
| **Enable Double Opt-In** | New subscribers are `PENDING_CONFIRMATION` and get a confirmation email |
| **Change email template** | Opens the confirmation email editor (only after the switch is on) |
| **Save** | Persists the switch. The email template is saved separately inside the editor |
The card below it — **Add transactional recipients to the marketing list** — is a different path. Turning that on creates receipt/OTP recipients as `SUBSCRIBED`. Double opt-in does not apply there.
## Customize the confirmation email
With the switch on, click **Change email template**.
_Subject, preview, and body. The blue button must point at `{{confirmUrl}}`._
| Data point | Detail |
| --- | --- |
| **Subject / Preview** | Inbox subject and preview text. Defaults are `Confirm your email address` |
| **`{{confirmUrl}}`** | Required. Type `@` and pick **Confirmation URL**, or `/confirm` to insert the confirmation button |
| **`{{name}}` / fields** | Same subscriber variables as campaigns. `@` opens the menu |
| **Snippets** | Type `/` to insert an organization snippet |
| **Default sender** | Confirmation emails always send from the organization's default sender |
| **Save email** | Writes the template. Missing `{{confirmUrl}}` falls back to the default template |
The recipient confirmation page (`You're all set`) follows **Settings → Language**, not the email body language. Translate the email yourself.
## Test the complete journey
Use a test inbox after saving the setting and email:
1. Submit a new email address through your public form or capture page.
2. In **Subscribers**, clear any active status filter, or filter by **Pending Confirmation**, to find the new contact. A pending contact is not shown when the list is filtered to subscribed contacts.
3. Open the contact and confirm that **Confirm your email address** appears in their recent email activity.
4. Open that email in the test inbox and click its confirmation button or link.
5. The confirmation page says **You're all set**. Back in Lumail, the contact is now `SUBSCRIBED`; any eligible subscriber-created or tag-added workflow can enroll and send its first email.
If the contact is still pending, check that the template contains `{{confirmUrl}}` on a button URL or link, then save the email template again. Do not replace it with a URL from a different subscriber: confirmation links are single-use and recipient-specific.
## After they confirm
The subscriber timeline shows that they **confirmed their email via the double opt-in link and subscribed to the list**. The confirmation-link click is labeled as such, not as a generic URL click.
Workflows that start on **subscriber created** or **tag added** wait until confirmation. Tags attached at signup are replayed after the click so tag-triggered workflows enroll a real `SUBSCRIBED` contact.
Campaigns only target `SUBSCRIBED`. Pending contacts never enter a send.
## What uses double opt-in
| Source | New subscriber | Confirmation email |
| --- | --- | --- |
| Capture page | `PENDING_CONFIRMATION` | Sent |
| Subscribers API / SDK (`POST /api/v1/subscribers` or `/api/v2/subscribers`) | `PENDING_CONFIRMATION` | Sent (unless `triggerWorkflows: false`) |
| API / SDK with `skipDoubleOptIn: true` | `SUBSCRIBED` | Not sent — no confirmation token |
| ClickFunnels / Systeme.io | `PENDING_CONFIRMATION` | Sent |
| Dashboard **Add Subscriber** | `PENDING_CONFIRMATION` | Sent only if **Trigger workflows** is on |
| Dashboard **Add Subscriber** with **Skip double opt-in** | `SUBSCRIBED` | Not sent |
| CSV import | `SUBSCRIBED` by default | Not sent — import writes status directly |
| Transactional API / SMTP / `lumail.emails.send` | `TRANSACTIONAL` or `SUBSCRIBED` | Ignored. Not a custom double-opt-in mechanism |
| Resubscribe of `UNSUBSCRIBED` / `TRANSACTIONAL` | `SUBSCRIBED` | Skipped |
`skipDoubleOptIn` defaults to `false`. New organizations have double opt-in on; existing organizations keep whatever they already stored. Trusted backends (checkout, server-side sync) should pass `skipDoubleOptIn: true` so those contacts stay `SUBSCRIBED` and tag-triggered workflows can enroll. Public forms must omit the flag.
`triggerWorkflows: false` still creates the pending subscriber when DOI is on. It skips the confirmation email. It is not a substitute for `skipDoubleOptIn`. Use `skipDoubleOptIn` for trusted sources; do not use either flag on a public form.
For the legal and evidence limits of `confirmedAt` / `confirmationIp`, see [GDPR in Lumail](/docs/legal/gdpr-in-lumail#native-and-custom-double-opt-in).
## Related documentation
- [GDPR in Lumail](/docs/legal/gdpr-in-lumail) — when to enable native confirmation
- [WordPress Plugin](/docs/integrations/wordpress) — public `[lumail_form]`, never skips DOI
- [Create Subscriber API](/docs/api-reference/api-subscribers-post) — signup payload and `triggerWorkflows`
- [Language](/docs/features/language) — confirmation page locale
- [Subscriber Events](/docs/features/subscriber-events) — `SUBSCRIBED` timeline events
- [Workflows](/docs/workflows) — enrollments start after confirmation
- [Account Verification](/docs/features/account-verification) — DOI also helps sender health
- [Migration to high deliverability emails](/docs/tutorials/migration-to-high-deliverability-emails) — branding, why-you-receive, OTP, and workflow setup
---
# Automatic list cleanup
Source: https://lumail.io/docs/tutorials/automatic-list-cleanup.md
Automatic list cleanup removes inactive subscribers so the list stays healthy. It is off until an owner or admin calculates a preview and turns the switch on from that receipt.
Do not invent a custom inactivity unsubscribe with the API. Use this setting.
## Watch the complete walkthrough
This three-minute walkthrough shows the complete journey: the eligibility rules, preview before enable, analytics after cleanup, the re-engagement email, a cleaned subscriber, and the recovery page.
If the player does not load, [watch the automatic list cleanup walkthrough on Tella](https://www.tella.tv/video/vid_cmu271jnv00070agm5l6x9vd8/view).
## What it does
With **Automatic list cleanup** on, Lumail regularly scans `SUBSCRIBED` contacts and unsubscribes anyone who:
- has not opened or clicked a marketing email in the interval you chose (30, 90, or 180 days)
- has not come back through a cleanup recovery link in that same interval
- has been subscribed for at least 7 days
- has at least 5 delivered marketing emails
- has a trustworthy subscription history
Everyone else is kept or deferred. Preview never changes a contact. Enabling only turns the setting on — the next scan applies it.
```
Settings → Configuration → Automatic list cleanup
↓
Preview (dry run + 10-minute receipt)
↓
Turn the switch on
↓
Daily scan (pages of 100)
↓
UNSUBSCRIBED + optional re-engagement email
↓
Click {{subscribeUrl}} → /resubscribe?token=…
↓
SUBSCRIBED again (or confirmation email if double opt-in is on)
```
## Enable it
1. Open **Settings → Configuration → Automatic list cleanup**. The URL is `/orgs/[your-org]/settings/configuration/automatic-cleanup`.
2. Pick **Remove after** (30, 90, or 180 days).
3. Leave **Send a re-engagement email** on if you want one last email after they are removed.
4. Click **Preview**. Nobody is unsubscribed.
5. Wait until the card shows how many would be removed (or **Nobody matches.**).
6. Turn the switch on, or click **Turn on cleanup**. The receipt expires after 10 minutes — preview again if it does.
7. Click **Save** only if you changed the interval or re-engagement toggle without enabling.
_Preview on the left, Save on the right. The switch stays locked until a completed preview exists._
| Control | What it does |
| --- | --- |
| **Automatic list cleanup** | Off until a completed preview receipt exists. On starts scans. Off disables immediately — no preview needed |
| **Remove after** | Inactivity window: 30, 90, or 180 days. Default 90 |
| **Send a re-engagement email** | After unsubscribe, send one transactional email with `{{subscribeUrl}}`. Default on |
| **Edit email** | Opens the re-engagement editor (only when the re-engagement switch is on) |
| **Preview** | Saves the interval + re-engagement toggle, then counts who would be removed. Does not enable |
| **Save** | Persists interval and re-engagement. Cannot turn the feature on |
Turning the main switch on without a completed preview shows **Preview first.** Changing the interval or re-engagement toggle after a preview invalidates the receipt — preview again.
When the preview finishes, the card shows **Nobody matches.** or **N of M contacts would be unsubscribed.** plus sample addresses. Enabling still requires that completed receipt, even if the count is zero.
## Who is never removed
| Keep / defer | Why |
| --- | --- |
| Open or click in the interval | Recent activity |
| Came back via `/resubscribe` in the interval | Recent recovery |
| Subscribed less than 7 days ago | New subscription |
| Fewer than 5 delivered marketing emails | Not enough sends to judge inactivity |
| Subscription history unknown | Missing or untrustworthy `SUBSCRIBED` event |
Each daily scan evaluates current subscribers against these criteria using recorded activity in the selected window. Historical tracking incidents do not restart a 30-, 90-, or 180-day waiting period. If a new tracking incident occurs during a scan, the affected batch is not finalized and the scan is retried.
Transactional, pending, already unsubscribed, and bounced contacts are outside the candidate set.
## Analytics after you enable
Once the switch is on, the same page shows cleanup analytics for the last 7 / 30 / 90 days:
| KPI | Meaning |
| --- | --- |
| **Cleaned** | Inactive subscribers unsubscribed automatically |
| **Recovered** | Share of cleaned subscribers who came back through the recovery link |
| **Re-engagement emails** | Recovery emails sent to cleaned subscribers |
| **Next scan** | When the next full pass is scheduled, plus the last cleanup time |
Below the KPIs: a **Cleaned subscribers** chart (unsubscribed vs recovered) and a **Recent cleanups** table (per day: cleaned, emailed, recovered).
Empty states tell you why nothing happened:
- a scan is paging the list (100 contacts at a time) and nobody has been unsubscribed yet
- the last full scan found nobody to remove
- the first scan is still being scheduled
Cleaned contacts appear here only after someone is actually unsubscribed — not when the preview finishes.
## Re-engagement email
Optional. Default subject is `Are you still interested?`. Default preview is `Stay on the list or we'll stop sending.`
Unsubscribe is applied first. The email is sent afterwards on the confirmation/transactional path — not as a campaign. If sending fails or is skipped, they stay `UNSUBSCRIBED`. Lumail logs the failure.
The template must include a real button or link with `{{subscribeUrl}}`. Type `@` and pick **Re-subscribe URL**, or put `{{subscribeUrl}}` on a button URL. Missing it refuses the save.
_Subject, preview, and body. The button must point at `{{subscribeUrl}}`._
| Data point | Detail |
| --- | --- |
| **Subject / Preview** | Inbox subject and preview text |
| **`{{subscribeUrl}}`** | Required. Opens `/resubscribe?token=` (24-hour single-use token) |
| **`{{unsubscribeUrl}}`** | Optional. Default footer includes it |
| **`{{name}}` / fields** | Same subscriber variables as campaigns. `@` opens the menu |
| **Snippets** | Type `/` to insert an organization snippet |
| **Default sender** | Always the organization's default sender |
| **Save email** | Writes the template. Missing `{{subscribeUrl}}` is rejected |
On a cleaned contact, the timeline shows **was unsubscribed by automatic list cleanup**. Open **View email** on the re-engagement send to read the exact message they received.
## Recovery page
The re-engagement link opens `/resubscribe?token=…`.
1. The page shows **Stay subscribed?** and a prefilled email field.
2. They confirm the address and click **Stay subscribed**. A different email is rejected — the field exists so they can see and confirm the address, not change it.
3. If they are already `SUBSCRIBED`, it says so and stops.
4. If **double opt-in** is on, status becomes `PENDING_CONFIRMATION` and they get the confirmation email. Campaigns wait for that click.
5. If double opt-in is off, they become `SUBSCRIBED` immediately. Unsubscribe guards are cleared. Workflows are not published from this recovery.
The token lasts 24 hours and is single-use. A second click on a used or expired link fails.
## Timeline
Filter a subscriber timeline by **Automatic list cleanup**.
| Event | Copy |
| --- | --- |
| `AUTOMATIC_LIST_CLEANUP` (admitted) | was queued for automatic list cleanup |
| `AUTOMATIC_LIST_CLEANUP` (finalized) | was removed by automatic list cleanup |
| `UNSUBSCRIBED` (`source: AUTOMATIC_LIST_CLEANUP`) | was unsubscribed by automatic list cleanup |
| `SUBSCRIBED` (`source: AUTOMATIC_LIST_CLEANUP_RECOVERY`) | came back from automatic list cleanup |
Unsubscribe reason stored on the contact is **Automatic list cleanup**.
## After you enable
A full pass runs **once a day**. The scan pages 100 subscribed contacts per organization until the list is finished, then waits 24 hours.
Disable anytime with the switch. No preview required. Existing unsubscribes stay unsubscribed — disable does not restore them.
Do not enable from the raw configuration API. Ask Lumail can preview and enable only with a completed receipt (`preview_list_cleanup` then `enable_list_cleanup`). `update_list_cleanup_settings` can disable or change the interval; it cannot turn the feature on.
## Related documentation
- [Enable Double Opt-In](/docs/tutorials/enable-double-opt-in) — recovery sends a confirmation email when DOI is on
- [Subscriber Events](/docs/features/subscriber-events) — timeline events
- [Bot detection](/docs/features/bot-detection) — how opens and clicks are recorded
- [GDPR in Lumail](/docs/legal/gdpr-in-lumail) — consent and unsubscribe evidence
- [Account Verification](/docs/features/account-verification) — list hygiene and sender health
---
# Create an API Token
Source: https://lumail.io/docs/tutorials/create-api-token.md
This tutorial walks you through creating an API token in Lumail. API tokens allow your applications, integrations, and automations to securely access your organization's data.
## Why use API tokens?
- **Programmatic access** — Automate subscriber management, send emails, and sync data from your applications.
- **Secure authentication** — Tokens are scoped to your organization and can be revoked anytime.
- **Integration ready** — Connect Lumail with tools like Make.com, Zapier, n8n, or your custom backend.
- **No user credentials** — Keep your account secure by using tokens instead of username/password.
## Prerequisites
- A Lumail account with an organization.
- Owner or admin role in the organization.
## Step 1 — Navigate to API Keys
1. Log in to your [Lumail dashboard](https://lumail.io/orgs/default).
2. Click on **API Keys** in the sidebar.
3. Click the **Generate API Key** button.
## Step 2 — Name your token
Give your token a descriptive name to identify its purpose:
- `Production API` — For your production application
- `Development` — For local development and testing
- `Zapier Integration` — For Zapier automation
- `Webhook Handler` — For processing workflow webhooks
Click **Create** to generate your token.
## Step 3 — Copy and save your token
Your token will be displayed only once. Copy it immediately and store it securely.
The token format is `lum_` followed by a 64-character string:
```
lum_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
```
Store it in your environment variables:
```bash
# .env.local (never commit this file)
LUMAIL_API_TOKEN=lum_your_token_here
```
## Step 4 — Use your token
Include the token in the `Authorization` header of your API requests:
```javascript
const response = await fetch("https://lumail.io/api/v1/subscribers", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.LUMAIL_API_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
email: "user@example.com",
name: "Jane Doe",
tags: ["newsletter"],
}),
});
const data = await response.json();
console.log(data);
```
## Security best practices
1. **Never commit tokens to version control** — Use environment variables or secret managers.
2. **Use separate tokens** — Create different tokens for development, staging, and production.
3. **Rotate tokens regularly** — Generate new tokens periodically and delete old ones.
4. **Delete unused tokens** — Remove tokens you no longer need from the settings page.
## Managing tokens
To view, or delete existing tokens:
1. Go to [API Keys](https://lumail.io/orgs/default/api-keys).
2. View all active tokens with their creation dates.
3. Click the delete icon to revoke a token.
Deleting a token immediately revokes access — any applications using it will fail authentication.
## Related Documentation
- [API Tokens Reference](/docs/api-reference/api-tokens) - Complete token documentation
- [Create Subscriber API](/docs/api-reference/api-subscribers-post) - Add subscribers
- [Send Email API](/docs/api-reference/api-emails-send) - Send transactional emails
- [Update Subscriber API](/docs/api-reference/api-subscribers-patch) - Update subscriber data
- [Tags API](/docs/api-reference/api-tags-get) - Manage tags
- [Track Events API](/docs/api-reference/api-events-post) - Track subscriber activity
- [Dynamic Promo Codes](/docs/tutorials/dynamic-promo-codes) - Use tokens in webhooks
- [Webhook Step](/docs/workflows/workflow-webhook-step) - Authenticate webhook callbacks
---
# Send Transactional Email with SMTP
Source: https://lumail.io/docs/tutorials/smtp-transactional-emails.md
Use Lumail's SMTP endpoint when an application can only send email through SMTP and cannot call `POST /api/v1/emails` directly. Common examples include auth providers, billing tools, no-code platforms, and legacy backends.
SMTP messages are treated as transactional by default. They use the same priority delivery lane as the transactional email API, so auth codes, magic links, password resets, and operational emails are not queued behind newsletter or campaign batches.
## When to Use SMTP
Use SMTP for:
- authentication codes and magic links
- password resets
- account invitations
- receipts and invoices
- product notifications
- other low-volume operational emails
Do not use the SMTP endpoint for newsletters, broadcasts, or marketing campaigns. Use Lumail campaigns and workflows for bulk sending so unsubscribes, segmentation, scheduling, and campaign reporting stay correct.
## Prerequisites
Before configuring SMTP, the organization needs:
1. A verified Lumail email domain.
2. A Lumail API token.
3. An SMTP-capable application that supports STARTTLS on port `587`.
4. A `From` address on the verified domain.
The API token and the verified domain must belong to the same Lumail organization.
## Step 1 - Verify a Sending Domain
The `From` address must use a verified email domain in Lumail.
1. Open your Lumail organization.
2. Go to **Settings** -> **Domains**.
3. Add your sending domain, for example `yourdomain.com`.
4. Add the SPF and DKIM DNS records shown by Lumail.
5. Wait until the domain status is **Verified**.
If your verified domain is `yourdomain.com`, valid sender examples include:
```text
auth@yourdomain.com
support@yourdomain.com
noreply@yourdomain.com
```
Lumail rejects SMTP messages when the `From` address does not belong to a verified email domain in the same organization as the API token.
## Step 2 - Create an API Token
The SMTP password is a Lumail API token, not your Lumail account password.
1. Open your Lumail organization.
2. Go to **Settings** -> **API Tokens**.
3. Click **Generate Token**.
4. Name it clearly, for example `Production SMTP`.
5. Copy the token immediately and store it in your application's secret manager.
The token starts with `lum_`.
## Step 3 - Configure Your SMTP Client
Use these settings in your external application:
| Setting | Value |
| -------- | ------------------------------------------ |
| Host | `smtp.lumail.io` |
| Port | `587` |
| Security | STARTTLS |
| Username | Your organization slug, or any label |
| Password | Your Lumail API token |
| From | An address on a verified Lumail domain |
| To | The recipient address for the notification |
The username is used as a label in SMTP logs. The password is what authenticates the request.
## Supabase Auth Example
For Supabase Auth custom SMTP, configure:
```text
Host: smtp.lumail.io
Port: 587
Security: STARTTLS
Username: your-org-slug
Password: lum_your_api_token
Sender email: auth@your-verified-domain.com
```
Use the same sender address in Supabase email templates. The sender domain must already be verified in Lumail.
## Nodemailer Example
```javascript
import nodemailer from "nodemailer";
const transport = nodemailer.createTransport({
host: "smtp.lumail.io",
port: 587,
secure: false,
requireTLS: true,
auth: {
user: "your-org-slug",
pass: process.env.LUMAIL_API_TOKEN,
},
});
await transport.sendMail({
from: "Auth Team ",
to: "user@example.com",
subject: "Your login code",
text: "Your login code is 123456.",
});
```
> **Test-mode recipients.** Fixture addresses such as `user@example.com` never send real email. See [Test-mode recipients](/docs/api-reference/test-mode).
## Test the Connection
You can test the SMTP endpoint with `swaks`:
```bash
swaks \
--server smtp.lumail.io \
--port 587 \
--tls \
--auth LOGIN \
--auth-user your-org-slug \
--auth-password lum_your_api_token \
--from auth@your-verified-domain.com \
--to user@example.com \
--header "Subject: Lumail SMTP test" \
--body "This email was sent through Lumail SMTP."
```
A successful response ends with:
```text
250 Queued 1 message(s)
```
That means Lumail accepted the email and queued it on the transactional priority lane. Final inbox placement still depends on the receiving mailbox and downstream delivery provider.
## Message Behavior
| Behavior | Default |
| -------------- | ------------------------------------------------------------------ |
| Delivery lane | Transactional priority |
| Recipients | 1 recipient per SMTP message |
| Attachments | Rejected |
| Size limit | 1 MB |
| Link tracking | Enabled |
| Open tracking | Enabled |
| Content format | HTML is preserved when present; otherwise text is sent as Markdown |
Send one SMTP message per recipient. If your application needs bulk sending, use Lumail campaigns or workflows instead.
## Troubleshooting
| SMTP response | Meaning | Fix |
| ------------- | ---------------------------------------- | ----------------------------------------------------------- |
| `535` | Invalid API token | Check the token starts with `lum_` and has not been deleted |
| `530` | Authentication required | Enable SMTP AUTH in your application |
| `550` | Invalid sender, recipient, or message | Verify the `From` domain and message content |
| `552` | Message too large or attachment rejected | Keep the message under 1 MB and remove attachments |
| `452` | Temporary quota, rate, or plan issue | Retry later or check organization limits |
| `451` | Lumail API temporarily unavailable | Retry with exponential backoff |
If your provider asks for SSL/TLS on port `465`, choose STARTTLS on port `587` instead. Lumail's SMTP endpoint is exposed on `587`.
## Related Documentation
- [SMTP Endpoint Reference](/docs/api-reference/smtp) - Connection settings and response codes
- [Create an API Token](/docs/tutorials/create-api-token) - Generate the token used as the SMTP password
- [Email Domains](/docs/domains/email-domains) - Verify the domain used in your `From` address
- [Send Transactional Email API](/docs/api-reference/api-emails-send) - Prefer this API when your application supports HTTP
---
# Send React Email Templates with Lumail
Source: https://lumail.io/docs/tutorials/react-email.md
[React Email](https://react.email) lets you write email templates as React components and render them to email-safe HTML. Lumail accepts that HTML directly through `html` on `POST /api/v2/emails`, so React Email covers the template layer and Lumail covers sending, domain authentication, subscriber records, and delivery tracking.
## When to Use This
Use React Email with Lumail for transactional email: receipts, password resets, magic links, invitations, order confirmations, and product notifications.
Campaigns are a different content pipeline: they accept `MARKDOWN` and `MAILY`, not `HTML`. Newsletters and broadcasts stay in Lumail campaigns and workflows so unsubscribes, segmentation, and campaign reporting remain correct.
## Prerequisites
1. A verified Lumail email domain, so your `from` address is allowed.
2. A Lumail API token (starts with `lum_`). See [Create API Token](/docs/tutorials/create-api-token).
3. A Node.js project that can render React on the server.
## Step 1 - Install the Packages
```bash
pnpm add lumail @react-email/components @react-email/render
```
`@react-email/components` provides the email-safe primitives. `@react-email/render` turns a component into an HTML string. `lumail` is the [TypeScript SDK](/docs/sdk/introduction).
To preview templates locally while you build them, add the React Email dev server:
```bash
pnpm add -D react-email
```
## Step 2 - Write the Template
Create `emails/order-confirmation.tsx`:
```tsx
import {
Body,
Button,
Container,
Head,
Heading,
Hr,
Html,
Link,
Preview,
Section,
Text,
} from "@react-email/components";
type OrderConfirmationProps = {
name: string;
orderNumber: string;
total: string;
receiptUrl: string;
};
export default function OrderConfirmation({
name,
orderNumber,
total,
receiptUrl,
}: OrderConfirmationProps) {
return (
Your order {orderNumber} is confirmed
Thanks for your order, {name}
Order {orderNumber} is confirmed. Total: {total}.
Questions?{" "}
Contact us
);
}
```
Pass per-recipient data as React props. A transactional send targets one recipient, so the values are already known at render time and you keep full type safety.
## Step 3 - Render to HTML
`render()` from `@react-email/render` v2 is asynchronous and returns the full HTML document.
```typescript
import { render } from "@react-email/render";
import OrderConfirmation from "@/emails/order-confirmation";
const html = await render(
,
);
```
Render in a `.tsx` file so JSX compiles. If your send logic lives in a `.ts` file, keep rendering in a separate `.tsx` module and import the resulting function.
## Step 4 - Send Through Lumail
```typescript
import { Lumail } from "lumail";
const lumail = new Lumail({ apiKey: process.env.LUMAIL_API_KEY! });
const { id } = await lumail.emails.send({
to: "customer@example.com",
from: "orders@yourdomain.com",
subject: "Your order A-1042 is confirmed",
html,
});
```
> **Test-mode recipients.** Fixture addresses such as `user@example.com` never send real email. See [Test-mode recipients](/docs/api-reference/test-mode).
The `preview` field is ignored for `HTML` content - only the Markdown and Tiptap pipelines inject it. The preheader comes from React Email's `` component in your template.
Each recipient of a transactional send becomes a Lumail contact if they are not one already (`TRANSACTIONAL` unless **Add transactional recipients to the marketing list** is on), and addresses on the blocklist are rejected before queueing.
The equivalent raw API call:
```bash
curl -X POST https://lumail.io/api/v2/emails \
-H "Authorization: Bearer $LUMAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "customer@example.com",
"from": "orders@yourdomain.com",
"subject": "Your order A-1042 is confirmed",
"html": "...rendered react email..."
}'
```
A success response means Lumail queued the email on the transactional priority lane. See [Send Transactional Email](/docs/api-reference/api-emails-send) for the full field list and response shape.
## Complete Example
A single server function that renders and sends:
```tsx
import { render } from "@react-email/render";
import { Lumail } from "lumail";
import OrderConfirmation from "@/emails/order-confirmation";
const lumail = new Lumail({ apiKey: process.env.LUMAIL_API_KEY! });
export async function sendOrderConfirmation(order: {
email: string;
name: string;
orderNumber: string;
total: string;
receiptUrl: string;
}) {
const html = await render(
,
);
return lumail.emails.send({
to: order.email,
from: "orders@yourdomain.com",
subject: `Your order ${order.orderNumber} is confirmed`,
html,
});
}
```
## React Props vs Lumail Variables
Lumail replaces `{{variable}}` placeholders in HTML content before sending. Both mechanisms work, and they are good at different things.
| Data | Use |
| -------------------------------------------------------- | ---------------- |
| Order totals, names, URLs, anything your app already has | React props |
| `{{unsubscribeUrl}}`, `{{onlineUrl}}` | Lumail variables |
| Lumail custom subscriber fields | Lumail variables |
Lumail owns the unsubscribe and view-in-browser URLs, so those must stay as placeholders.
Two limits are worth knowing before you rely on placeholders in a React Email template:
- Placeholder names must be word characters. Hyphenated organization variables such as `{{org-name}}` are not substituted in `HTML` content and are delivered literally. Pass organization values as React props instead.
- `{{unsubscribeUrl}}` resolves to an empty string on transactional sends, because a transactional email has no unsubscribe link. It is only meaningful when `transactional` is false.
See [Send Email in HTML](/docs/api-reference/api-emails-html) for the full variable list.
### Escaping Braces in JSX
`{{unsubscribeUrl}}` inside JSX is parsed as a JavaScript expression containing an object literal, not as text. Always pass it as a string:
```tsx
// Correct
Unsubscribe
Hello {"{{name}}"}
// Broken - JSX evaluates the braces
Unsubscribe
```
## What Lumail Does to Your HTML
Your rendered document is sent through mostly untouched. Lumail applies these transformations:
- **Variable replacement** - `{{...}}` placeholders are substituted with subscriber values.
- **Open tracking** - a 1x1 pixel is inserted just before `` when open tracking is on. React Email always emits a `
`, so the pixel lands inside the document.
- **Unsubscribe fallback** - for non-transactional sends only, if the HTML contains no `{{unsubscribeUrl}}`, Lumail appends an unsubscribe block to the end of the string, after your closing `
