Sending email

There are four ways to send an email. They all go through the same delivery settings, use a template’s published version when they name one, and appear in Mail activity.

Way	Best for	Delivered
A flow’s Send email block	Anything your app triggers: receipts, notifications, digests	In the background, retried
Compose in Studio	One-off messages, and scheduling a message by hand	When you send, or at the time you set
Your server over HTTP	Sending from your own backend, scripts or jobs	Immediately, or at a time you set
Sign-in emails	Codes, links, resets and invitations	Automatically, in the background

From a flow

Add the Send email block to a flow. It’s the usual way to send email from an app: trigger the flow from an event (a record created, a payment received), a schedule, a route or another flow.

Setting	Meaning
To	One address, or a list of addresses. Templates work: `{{ steps.load.output.email }}`
Template	The name of a published template
Data	The values the template reads, as an object mapped from earlier steps
Subject, Text, HTML	Write the message directly instead of using a template. With a template, a subject you set here replaces the template’s.

The block queues the message and continues straight away. Its output is { "queued": true, "job_id": "…" }. The message is sent in the background, so a slow provider never slows the flow or the request that started it. If the provider fails, the send is retried up to 3 times, waiting a few seconds longer each time. Each attempt is logged, and you can see the job under Activity → Jobs.

Example: a receipt when an order is paid

Make a template order-confirmation that reads customer.first_name, order.number and order.items, and publish it.
Make a flow, and an event subscription that runs it on orders.updated (or your own orders.paid event). The flow receives the event as input.event; a table’s events carry the record at input.event.payload.record.
Add Get record (id customer) to load the customer by {{ input.event.payload.record.customer_id }}.
Add Send email:

{
  "to": "{{ steps.customer.output.email }}",
  "template": "order-confirmation",
  "data": {
    "customer": { "first_name": "{{ steps.customer.output.first_name }}" },
    "order": "{{ input.event.payload.record }}"
  }
}

Because "{{ input.event.payload.record }}" is the whole setting, the order object is passed as an object, not as text. See passing values between blocks.

Send to many people

A list in To sends one message with everyone as a recipient, so they can see each other’s addresses. To send each person their own message, loop over them with the For each block and put Send email inside it. That’s also the only way to personalise each message.

Compose

Mail → Compose writes and sends one message.

Field	Meaning
To	Type addresses, or search your app’s users by name or email
Cc, Bcc	Copies. Bcc recipients are hidden from the others.
From	One of your senders; the default if you don’t choose
Reply to	Where replies go. Defaults to your support email.
Start from a template	Pick a template, then fill in its values
Subject, Preheader, body	Write freely, and Insert a value to use template syntax
Attachments	Files up to 10 MB in total
Send later	Pick a date and time; it’s stored as scheduled
Save as template	Keep what you wrote as a new template

A scheduled message is rendered when you schedule it, so it goes out exactly as you saw it, even if the template changes in between. Cancel it from Mail activity before it’s sent.

From your server

Your server can send through the management API with a secret key. The key needs mail access: a key with no scopes, or one holding mail:write (see Keys and security).

curl -X POST "$PAWABASE_URL/platform/v1/envs/production/mail/send" \
  -H "apikey: $PAWABASE_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{
    "to": ["ada@example.com"],
    "template": "order-confirmation",
    "data": { "customer": { "first_name": "Ada" }, "order": { "number": "#1042", "items": [] } }
  }'

const res = await fetch(`${process.env.PAWABASE_URL}/platform/v1/envs/production/mail/send`, {
  method: "POST",
  headers: { apikey: process.env.PAWABASE_SECRET_KEY!, "content-type": "application/json" },
  body: JSON.stringify({
    to: ["ada@example.com"],
    template: "order-confirmation",
    data: { customer: { first_name: "Ada" }, order: { number: "#1042", items: [] } },
  }),
});
if (!res.ok) throw new Error(`mail failed: ${res.status} ${await res.text()}`);
const sent = await res.json(); // { id, message_id, suppressed, to }

import os, httpx

res = httpx.post(
    f"{os.environ['PAWABASE_URL']}/platform/v1/envs/production/mail/send",
    headers={"apikey": os.environ["PAWABASE_SECRET_KEY"]},
    json={
        "to": ["ada@example.com"],
        "template": "order-confirmation",
        "data": {"customer": {"first_name": "Ada"}, "order": {"number": "#1042", "items": []}},
    },
)
res.raise_for_status()
sent = res.json()

The request

Field	Type	Meaning
`to`	list of addresses	Required, at least one
`cc`, `bcc`	lists of addresses	Optional copies
`template`	text	A published template’s name
`data`	object	Values for the template
`subject`, `html`, `text`	text	Write the message directly. With a template, these replace the template’s parts you set.
`from_email`	text	A sender address; the default sender if omitted
`reply_to`	text	Where replies go; your support email if omitted
`attachments`	list	Each `{ "filename", "content_type", "content" }`, where `content` is the file’s bytes in base64. 10 MB in total.
`scheduled_at`	ISO time	Send later. Omitted, or in the past, sends now. A time without a zone is read as UTC.

The response

Sent now:

{ "id": "01JD…", "message_id": "<…@smtp.example.com>", "suppressed": false, "to": ["ada@example.com"] }

Scheduled:

{ "id": "01JD…", "scheduled": true, "scheduled_at": "2026-11-07T09:00:00+00:00", "to": ["ada@example.com"] }

suppressed: true means delivery is paused: the message was recorded, not sent.

Errors

Status	Meaning
`404`	No template by that name, or it has never been published
`422`	A problem in the template (bad syntax, a missing nested value), an attachment that isn’t base64, or an invalid request
`502`	Your provider refused or couldn’t be reached. The message is logged as failed with the reason.

Sending over HTTP happens during the request and isn’t retried for you. For mail that must not be lost, send from a flow, which queues and retries, and call the flow from your server with pawabase.flows.run(...) (see Flows).

Send a test

POST /platform/v1/envs/{env}/mail/test sends a message immediately with the same fields as above, without attachments or scheduling. Its subject defaults to Pawabase test message. Studio’s test buttons use it.

Preview without sending

POST /platform/v1/envs/{env}/mail/render renders a subject, html and text with data, exactly as sending would, and returns them. Use it to show a preview in your own admin tools. The sign-in system sends its emails itself: verification links and codes, sign-in links, password resets, invitations and security notices. They use the default sender and your brand, are queued and retried like flow mail, and appear in Activity with the source identity. Choose their wording in Email templates.

Choosing a sender

With no from_email, mail comes from the default sender set in Delivery.
Your provider must accept the address. Use addresses on a domain you’ve verified with it.
Use separate senders for different kinds of mail (orders@, support@, hello@) so people recognise them and replies go to the right place.

Usage and limits

Every delivery attempt counts towards your plan’s monthly emails, retries included, because your provider charges for each one. Suppressed messages count too. See Plans and limits.

Good practice

Send from flows for anything automatic: you get queuing, retries and a trace.
Use templates, not inline HTML, so wording changes don’t need a deploy.
Pass ids and look things up in the flow rather than sending huge data objects.
In development, pause delivery so tests never email real people.

Getting started

Templates

Send and track

Production

From a flow

Example: a receipt when an order is paid

Send to many people

Compose

From your server

The request

The response

Errors

Send a test

Preview without sending

Choosing a sender

Usage and limits

Good practice

​From a flow

​Example: a receipt when an order is paid

​Send to many people

​Compose

​From your server

​The request

​The response

​Errors

​Send a test

​Preview without sending

​Sign-in emails

​Choosing a sender

​Usage and limits

​Good practice

From a flow

Example: a receipt when an order is paid

Send to many people

Compose

From your server

The request

The response

Errors

Send a test

Preview without sending

Sign-in emails

Choosing a sender

Usage and limits

Good practice