Emails
Transactional emails
Open up email.ex and you will see a list of functions that generate Swoosh email structs. Eg:
def confirm_register_email(email, url) do
base_email()
|> to(email)
|> subject("Confirm instructions")
|> render_body("confirm_register_email.html", %{url: url})
|> premail()
end
If I run this function in IEX I can see the Swoosh struct:
A Swoosh.Email struct can be delivered to an email address by a Swoosh mailer (see mailer.ex). Eg:
MyApp.Email.confirm_register_email(user.email, url)
|> MyApp.Mailer.deliver()
So email.ex creates the Swoosh structs and the functions for actually delivering emails like the previous code example are in lib/petal_pro/notifications/user_mailer.ex (PetalPro.Notifications.UserMailer). Think of email.ex functions like view templates, and user_mailer.ex functions like controller actions.
The steps to creating a new email:
-
Create the function to generate a Swoosh struct in
email.ex -
Ensure it looks good by navigating to
http://localhost:4000/dev/emailsand creating a new action inemail_testing_controller.exthat renders thehtml_bodyvalue of the struct -
Create a new
user_mailer.exfunction for use in your application
To see a more detailed write up on creating an email — see this section in the “Complete web app” guide.
Email provider: Resend
Petal Pro v4 uses Resend as the sole transactional email provider via the Swoosh.Adapters.Resend adapter. AWS SES has been removed.
Configuration
Set the RESEND_API_KEY environment variable (get it from your Resend dashboard):
fly secrets set RESEND_API_KEY="re_..."
In runtime.exs the mailer is configured automatically when the key is present:
config :petal_pro, PetalPro.Mailer,
adapter: Swoosh.Adapters.Resend,
api_key: System.fetch_env!("RESEND_API_KEY")
No MAIL_PROVIDER env var is needed — Resend is the only option.
Email template components
Petal Pro ships a set of HEEx email layout components you can compose to build consistent, well-styled transactional emails. These live in lib/petal_pro_web/components/email_components.ex.
Spacing
Drop a gap between sections. height is in pixels (default 35):
<p>First section</p>
<EmailComponents.gap height="32" />
<p>Second section</p>
Buttons
button (and button_centered, which wraps it in centered) takes a to URL, a color (blue, green, red or gray) and a size (sm, md or lg). Use gray for secondary actions:
<EmailComponents.button to={@url} color="gray">
Manage preferences
</EmailComponents.button>
Callout boxes
Use callout_box to draw attention to important information. color is blue (default), green, yellow or red:
<EmailComponents.callout_box color="yellow">
Your confirmation code is <strong>482901</strong>. It expires in 15 minutes.
</EmailComponents.callout_box>
There’s also gray_box, dotted_gray_box, top_border and small_text. See templates/email/template.html.heex for examples.
Marketing emails with Resend
Marketing emails are emails you wish to send to your whole subscriber base or some segment of them to push a marketing or product update. They differ from transactional emails in that you don’t program them in code — you compose them in the Resend dashboard and hit send.
We use Resend for marketing because it has a clean API, generous free tier, and a good unsubscribe / deliverability story out of the box. Transactional email goes through Swoosh (with the Resend adapter in prod). The contact sync below is a separate concern.
How sync works
Contacts (your users) sync to Resend automatically:
-
After registration, after a profile update and when a user hits the marketing unsubscribe link, an Oban job (
PetalPro.Workers.ContactSyncWorker) runsPetalPro.MarketingEmail.sync_contact/1 -
That call upserts the user as a Resend contact (email, first name, and
unsubscribedfrom their:marketing_notificationsemail preference) -
Only GDPR account deletion (
PetalPro.Accounts.GDPR.execute_data_deletion/1) removes the contact, by callingPetalPro.MarketingEmail.delete_contact/1. Suspending a user (Accounts.suspend_user/1) or soft-deleting one (Accounts.delete_user/1) leaves the contact in Resend, so remove it yourself if you need to
To backfill existing users (e.g. after first deploy), run:
# In iex
PetalPro.MarketingEmail.sync_all_contacts()
Each user gets its own Oban job with a random 0-120s delay to stay under Resend’s default rate limit.
Segment
Resend slices contacts via segments (formerly “audiences”). Pro uses one: set RESEND_SEGMENT_ID and every synced contact is added to that segment when it’s upserted. Leave it unset and contacts are synced with no segment. If you want more segments, extend upsert_contact/1 in PetalPro.MarketingEmail.
Inbound webhook
Resend sends events to POST /webhooks/resend (handled by PetalProWeb.ResendWebhookController). Signatures are verified via svix HMAC against RESEND_WEBHOOK_SECRET.
| Event | Action |
|---|---|
contact.updated with unsubscribed: true |
Turns off the user’s :marketing_notifications email preference |
email.bounced |
Logged to Logs for review |
email.complained |
Logged to Logs for review (spam complaints damage sender reputation) |
Required env vars
RESEND_API_KEY=re_...
RESEND_SEGMENT_ID=... # optional
RESEND_WEBHOOK_SECRET=whsec_...