EmailsCopy Anchor Link

Flo sends transactional emails to your customers for you: order confirmations, receipts, subscription emails, dunning emails and more. They carry your brand, and you decide which ones are sent, what they say and where replies go. This guide explains how the email system works. Every endpoint it mentions is described in the Emails API reference, and each one is also a FloPay MCP tool.

Who this is forCopy Anchor Link

This guide is for merchants who set up their customer emails in the dashboard, and for developers who manage them through the REST API or an MCP assistant.

Email typesCopy Anchor Link

Each email Flo can send your customers has a type. You switch each type on or off on its own (see Switches and defaults), and the type ID is how the API names it.

The three dunning emails follow the retry schedule of your dunning policy.

Abandoned cart, renewal reminder and trial ending emails are not available yet.

Security emails, such as one-time sign-in codes, have no type ID and are always sent: you cannot switch them off.

TemplatesCopy Anchor Link

Every email starts from Flo's default content, laid out in your brand: your logo, colors, font and footer text. You can replace that content with a template of your own. GET /v1/email-templates lists every email you can give your own template, by message type (for example customer.order_confirmation), with whether it is switched on and whether Flo's default or your published template is sent. An email that is not in that list is sent with Flo's content.

Structured slots or custom HTMLCopy Anchor Link

A template is written in one of two modes:

• Structured slots (mode is structured): you write the text of each slot of Flo's layout. The subject, the heading and the paragraphs are required. A preheader, a highlight, a button or buttons, and a closing are optional. Flo keeps the layout, so the email renders well in every mail client.
• Custom HTML (mode is html): you write the subject and the whole html body yourself. Flo sanitizes the HTML, and every value a variable prints into it is escaped.

Each text of a template is at most 100 KB. In both modes Flo adds its own footer after your content, with your brand name followed by "via FloPay", your support contact and, for an email that has one, the unsubscribe link.

Draft, preview, test send and publishCopy Anchor Link

Every change starts as a draft, so nothing your customers receive changes until you publish:

1. Save a draft. A draft changes nothing that is sent.
2. Preview the draft with sample data. The preview renders it the way a real email is rendered, with the sample data of its type and your brand, and lists every problem that would stop it from being published. A preview changes nothing.
3. Send a test email to one address. Its subject starts with [Test]. Test sends are limited to 10 per rolling hour and 50 per rolling day for your account, and past either limit the API answers 429 with a Retry-After header. A test send to an address on your suppression list is refused.
4. Publish the draft. Flo validates it first and refuses it with every problem it finds: Liquid that does not parse, a variable the email type does not have, or a link the type requires that is missing. Once published, it is what your customers receive.

Reset to the defaultCopy Anchor Link

Reset discards your draft and stops sending your published template, so your customers receive Flo's default again. Who reset the template and when is recorded.

The endpoints for each step are in Templates in the API reference.

Variables and filtersCopy Anchor Link

Templates are written in Liquid, in both modes. Print a variable between double curly braces, such as {{ customer.first_name }}, loop over a list with a for tag, and change how a value prints with a filter after a |.

Each email type has its own variables, in groups: client (your business), customer, items (a list of what was bought), payment, subscription, checkout_session and links. A type has only the groups that fit it: the order confirmation has no subscription, and the subscription emails have no checkout_session. Money values are objects with an amount in minor units and a currency, and dates are ISO 8601 times in UTC, so print them with a filter.

Flo supports the standard Liquid filters, such as default, upcase and capitalize. For money values and dates, use these filters:

An order confirmation, for example:

Hi {{ customer.first_name | default: "there" }},

Thanks for your order from {{ client.name }}.

{% for item in items %}
{{ item.quantity }} x {{ item.name }}: {{ item.total | money }}
{% endfor %}

Total paid: {{ payment.amount | money }} on {{ payment.created_at | date: "%-d %B %Y" }}.
Your payment reference is {{ payment.reference }}.

A few rules keep templates safe and predictable:

• A variable can be empty, for example a customer whose first name is not known. Give it a fallback with default.
• A template sees only the variables of its type. Publishing refuses a variable the type does not have, and an unknown filter.
• The include, render and layout tags are not allowed: a template is one self-contained text.
• Some types require a link in every template, such as links.manage, where a customer updates their payment details. Publishing refuses a template without it.

The full list of variables for each type, with their types, descriptions, sample values and required links, comes from GET /v1/email-templates/schemas. Use it as the source of truth: the schemas can gain variables without a change to this guide.

Switches and defaultsCopy Anchor Link

Each email type has a switch. A switched-off email is not sent, but its webhooks still fire, so your own systems keep receiving the events. Flo records the email it did not send in the email log as skipped. Switching an email on does not send it for anything that happened before.

Where the switches start:

• New clients start with every email switched on.
• Existing clients start with every email switched off, and are prompted to review their emails before they switch them on. The exceptions are the payment receipt, payment declined and first dunning emails, which kept the setting of the receipt and payment-failed switches you had before.

The setup checklist in the dashboard asks you to review your emails. Changing a switch, a setting or the Reply-To does not count as the review: you confirm it yourself, in the dashboard or with POST /v1/setup-checklist/review.

Some types also have settings of their own. They are listed next to the switch, and you change both with Switch an email on or off.

Sender domainCopy Anchor Link

The default senderCopy Anchor Link

By default your emails are sent from no-reply@flopay.com, shown with your brand name followed by "via Flopay" (for example Northwind Studio via Flopay), and replies go to your Reply-To. A Reply-To is required: it is the address your customers reach when they reply to any email Flo sends for you, and the support contact in the order confirmation footer. Once set, you can change it but not clear it. This is the normal setup, and it needs nothing at your DNS host.

Send from your own domainCopy Anchor Link

The advanced option is to send from a subdomain of your own domain that you delegate to Flo, mail.<client-domain> unless you choose another label (for example mail.shop.com). Flo hosts that subdomain and writes every record mail needs inside it, so you publish only four NS records, all at mail.<client-domain>. The dashboard and the API show the records for your domain. They look like this:

Nothing changes at your root domain, and you add no other record.

1. Add the domain. Give your root domain, such as shop.com. Flo sets up mail.shop.com and answers pending, with the four NS records.
2. Publish the four NS records at your DNS host.
3. Verify. Flo checks each NS record and the records it wrote itself. When every check passes, the domain is verified and new mail goes from it, for example from billing@mail.shop.com. The part before the @ is your From local part, billing unless you change it. When a check fails, the answer names the failing records. A DNS lookup that times out is reported as unknown and changes nothing.

Until the domain is verified, and again if it breaks, your emails go from the default sender. The dashboard shows a red callout only for a delegation that is started but not verified yet, or one that is broken: verified once and failing now. With no sender domain there is no callout, because the default sender is a complete setup.

If you stop using the subdomain, delete the sender domain: mail goes from no-reply@flopay.com again at once. Then take the four NS records off your DNS host.

The endpoints are in Sender domain in the API reference.

Email log and suppressionCopy Anchor Link

The email log lists every email Flo sent or tried to send for you, newest first, with its type, recipient and delivery status:

Each entry links to the payment, subscription or checkout session it is about, when that is known. Filter the log by linkedResourceType (payment, subscription or checkout_session) and linkedResourceId to see every email about one record, or by status, type, recipient and createdAt. See Email log in the API reference.

Suppression listCopy Anchor Link

When an email to an address hard bounces, or its recipient makes a spam complaint, Flo adds the address to your suppression list and stops sending to it. Later emails to that address are logged as suppressed, and a test send to it is refused. Each entry says why the address was suppressed (hard_bounce or complaint) and which log entry caused it.

The suppression list is read-only: removing an address from it is not available yet. See Suppression list in the API reference.

Use it from an MCP assistantCopy Anchor Link

Every operation in this guide is also a FloPay MCP tool, except confirming the email review, which stays REST only. Reads are read-only tools. Changes are actions: the assistant shows you what will change and runs the action only after you confirm it. The Emails API reference names the tool for each endpoint, and the tool reference describes every tool.

RelatedCopy Anchor Link

• Emails API reference
• MCP tool reference