Viewing latest docs.
Switch version: v3

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:

  1. Create the function to generate a Swoosh struct in email.ex
  2. Ensure it looks good by navigating to http://localhost:4000/dev/emails and creating a new action in email_testing_controller.ex that renders the html_body value of the struct
  3. Create a new user_mailer.ex function 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) runs PetalPro.MarketingEmail.sync_contact/1
  • That call upserts the user as a Resend contact (email, first name, and unsubscribed from their :marketing_notifications email preference)
  • Only GDPR account deletion (PetalPro.Accounts.GDPR.execute_data_deletion/1) removes the contact, by calling PetalPro.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_...