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

1. Create a Postmark account and a server token.
2. Add it as a secure system setting named postmark_token — see Email configuration.
3. Set email_default_from to an address on your verified sender domain (e.g. noreply@yourdomain.com).
4. 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

1. Pick the trigger: form submit, storage_event (document created/updated), schedule_repeating_event (digests), or another API call.
2. Collect what the mail needs: recipient profile, order, or template values — usually one function_search or function_get_document.
3. Use the Postmark send blocks (search postmark in the block library) with to/subject/body from your data — the shape from the email template.
4. 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.

Was this page helpful? Tell us what to improve · RUAL Docs is an integral component of the RUAL ecosystem