Email System Setup

From zero to sending: tokens, from-addresses, templates, flows that trigger mail, and deliverability discipline.

Email on RUAL runs through Postmark: the cluster holds your server token, blueprints trigger sends, and you keep templates and recipients in storage. This tutorial sets the whole thing up in order.

Step 1, Prerequisites

Create a Postmark account and a server token.
Add it as a secure system setting named postmark_token. See Email configuration.
Set email_default_from to an address on your verified sender domain (e.g. noreply@yourdomain.com).
Optionally set messagebird_originator if you also send SMS for 2FA.

From this point, platform emails (password resets) already work. The rest is your own mail.

Step 2: Sending from a Flow

Pick the trigger: form submit, storage_event (document created/updated), schedule_repeating_event (digests), or another API call.
Collect what the mail needs: recipient profile, order, or template values: usually one function_search or function_get_document.
Use the Postmark send blocks (search postmark in the block library) with to/subject/body from your data. The shape from the email template.
Handle the send result: success/error pins → function_console_log while developing, and onto a mail-log document in production.

Step 3: Templates That Survive Edits

Keep subjects and bodies in storage (a mail_templates storage) with keys like welcome, reset-reminder, weekly-digest: edit content without touching the blueprint.
Build the final body with object_new_fields + text blocks, merging template with per-mail data (name, links, amounts).
Version links with full URLs (https://your-cluster/...): emails have no relative paths.

Step 4: Bulk and Scheduled Mail

Never loop-and-send inline in a request: enqueue per-recipient jobs with function_custom_execute_from_queue and let the queue drain them. See Queue.
Scheduled digests: schedule_repeating_event → gather since-last-run (range query on _meta.created) → one mail per user.
Idempotency: record last_sent_at per user/digest so retries never double-send.

Deliverability Discipline

Verify the sender domain in Postmark before sending anything (SPF/DKIM handled there).
One clear from-address per purpose; don't rotate from-addresses mid-thread.
Log every send (to, template, status, error) to a storage. You will need it the first time a user says "I never got it".
Test with a private alias first; Postmark's activity view confirms delivery before you blame the blueprint.

Next Steps

System Settings Reference postmark_token, email_default_from, and secure values. Queue Bulk and scheduled sending without blocking requests. Storage Events Triggering mail on document changes.

Frequently asked

How do I set up email sending on a RUAL cluster?

Create a Postmark server token, add it as a secure system setting named postmark_token, and set email_default_from to an address on your verified sender domain. From that point platform emails like password resets already work, and blueprints send their own mail with the Postmark send blocks.

How do I send bulk or scheduled email in RUAL?

Never loop-and-send inline in a request: enqueue per-recipient jobs with function_custom_execute_from_queue and let the queue drain them. Scheduled digests run from schedule_repeating_event, gathering what changed since the last run, and recording last_sent_at per user so retries never double-send.

How do I edit email content without changing blueprints in RUAL?

Keep subjects and bodies in a mail_templates storage with keys like welcome or weekly-digest, and build the final body by merging the template with per-mail data. Use full URLs for links, because emails have no relative paths.