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