Email via Postmark

Why you provide your own Postmark account

• We could host sending for you. But if one of your customers (or one of your customers' customers) sends bulk unsolicited mail, the shared sending reputation tanks. So does everyone else's deliverability.
• With YOUR Postmark account, you own your reputation. Your bounce rates, complaint rates, and engagement metrics are yours to manage. Your deliverability problems stay yours.
• Postmark also has a partner program. If you sign up via [our affiliate link — placeholder; the user will add the real URL later], we get a small kickback that funds LeadRails development.

Sign up for Postmark

1. Visit https://postmarkapp.com and sign up. The free tier gives you 100 emails a month for testing. Paid starts at $15/mo for 10k emails.
2. After sign-up, you land in your first "Server". Postmark uses servers as logical email-sending containers.
3. The default server is fine to start. Create more later if you want to separate domains.

Verify your sending domain

1. Settings, then Sender Signatures, then click "Verify Domain".
2. Add the DNS records Postmark prompts for (SPF, DKIM, optional Return-Path).
3. Wait 5 to 15 minutes for DNS propagation, then click "Verify".
4. Once verified, you can send from any address @yourdomain.com.

This step matters. Postmark rejects sends from an unverified domain. See "Verify connection" below for how LeadRails checks this for you before the first lead is sent.

Get your Server Token

1. Server, then the API Tokens tab.
2. Click "Show server token" or generate a new one.
3. Copy the token. It looks like 1a2b3c4d-5e6f-7890-abcd-ef0123456789 (a UUID).
4. This token is server-scoped, not account-scoped. It can only send from this one Postmark server.

Get your Account Token (optional)

1. Account settings, then the API Tokens area, then "Account API Tokens".
2. Copy the account-scoped token.
3. This one is optional. LeadRails uses it only during "Verify connection" to confirm your sending domain is verified. It is never used to send. The server token cannot read that state, which is why this is separate.

Two ways to compose the email

Pick one. You set this per destination.

• Inline templates. You write the subject and HTML body as Mustache-style templates in LeadRails. LeadRails fills in the variables from each lead at send time. Good for a quick single-line notification.
• Postmark template. You author the email in Postmark (subject, layout, body) and give LeadRails the template id or alias. LeadRails sends the lead's fields as the template's variables. The variable values come from the route mapping. Postmark owns the design. Better for anything you want to look polished.

You cannot set both on one destination. If you enter a template id or alias, leave the inline subject and body blank.

Set up your destination in LeadRails

1. Sign in, then Destinations, then New.
2. Adapter type: Email — Postmark.
3. Server token: paste from Postmark.
4. Account token (optional): paste if you want domain verification checked at connect time.
5. From address: a verified address on your Postmark domain (e.g. leads@yourdomain.com).
6. From name (optional): Your Brand Name, shown in the inbox.
7. Recipient template: {{email}} (sends to the lead's email by default). Used in both modes.

If you are using inline templates

1. Subject template: e.g. New lead: {{name}}.
2. HTML body template: the message body. Mustache-style variables ({{name}}, {{phone}}, {{utm_source}}) are filled in at send time. Note: the form is a single-line input today. Paste a single-line HTML template, or use the API for multi-line templates.
3. Plain-text body (optional): fallback for clients that do not render HTML. If omitted, Postmark auto-strips the HTML.

If you are using a Postmark template

1. Postmark template ID: the numeric id from your template in Postmark (e.g. 12345678).
2. Or Postmark template alias: the string alias you gave the template. Set one, not both.
3. Leave the inline subject and body fields blank.
4. Set up a route from your source to this destination and map lead fields onto the template's variables. Whatever the route mapping emits becomes the template's variable values. If no mapping is set, LeadRails sends the lead's standard fields (name, email, phone, company, message, and so on) as the variables.

8. Message stream (optional): defaults to your server's "outbound" stream. Use a different stream if you split broadcast and transactional in Postmark.
9. Click Create.

Available variables

• Inline mode, top-level lead fields: {{name}}, {{email}}, {{phone}}, {{company}}, {{source_url}}, {{utm_source}}, {{utm_campaign}}, and more.
• Inline mode, nested access: {{lead.email}}, {{event.event_id}}.
• Inline mode: missing variables resolve to an empty string. They do not throw.
• Template mode: the variables are whatever your route mapping emits, matched to the variable names in your Postmark template. The recipient still comes from the Recipient template above, not the mapping.

Example inline subject: New lead from {{utm_source}}: {{name}} resolves to New lead from google: Jane Doe.

Verify connection

1. Open the destination, then Advanced, then Verify connection.
2. LeadRails calls Postmark's /server endpoint to confirm the server token is valid. No test email is sent.
3. If you added an account token, LeadRails also calls Postmark's /domains endpoint and confirms your From address's domain has DKIM verified. An unverified domain fails here, with the domain named, instead of failing at the first real send.
4. Green checkmark means ready.

Without an account token, LeadRails can still confirm the server token, but it cannot check your domain. It will tell you so and suggest adding the token.

Send a test email

1. Sources, then your source, then Settings. Make sure a route exists to your Postmark destination.
2. Click "Send test event".
3. A real email lands in the configured recipient inbox within seconds. Postmark is fast, usually sub-second.
4. Postmark's Activity, then Outbound, logs the message.

Troubleshooting

401 / 422 + "UnauthorizedRequest"

Server token is wrong. Re-copy from Postmark.

Verify connection says the account token was rejected

The account token is wrong or is a server token pasted by mistake. Re-copy the account-scoped token, or clear the field to skip the domain check.

Verify connection says the sending domain is not verified

Your From address is on a domain whose DKIM is not confirmed in Postmark. Finish "Verify Domain" under Settings, then Sender Signatures, then verify again.

422 + "InactiveRecipientsError"

Postmark hard-bounced this recipient before. They are on Postmark's suppression list. Reactivate them via Postmark's API, or use a different test recipient.

422 + "InvalidEmailRequest"

Subject empty, body empty, or From address not verified in Postmark. Check all three. LeadRails flags this as a destination config problem.

Sender signature error

Your From address is on a domain you have not verified in Postmark. Visit Settings, then Sender Signatures.

Template mode: a variable renders blank or the send is rejected

The route mapping did not emit a variable your Postmark template expects, or emitted one it does not. Postmark returns a 422, which LeadRails flags as a destination config problem. Line up the mapping's output keys with the template's variable names.

High bounce rate alerts in Postmark

Your lead data has bad emails. Validate emails in your source form, or filter at the LeadRails route layer.

What is yours, what is ours

Your responsibilities

• You are the sender of record. Anti-spam compliance (CAN-SPAM, CASL, GDPR consent for EU recipients) is yours to manage.
• Postmark requires confirmed opt-in for marketing sends. Lead-routing emails count as transactional. If you send anything that looks like marketing, follow Postmark's content policies.
• Postmark's Bounce and Spam Complaint webhooks let you handle bounces upstream. Wire them into your source form to stop re-sending to known bad addresses.

LeadRails's responsibilities

• Send your message to Postmark reliably. We retry failed deliveries up to 5 times with backoff, dead-letter what still fails, and keep an audit trail.
• Surface delivery failures in your Jobs page and Alerts inbox.
• Mask your tokens in the UI.
• Re-check SSRF guards: not applicable here. Postmark is a fixed endpoint, so there is no customer-supplied URL to guard.