Emails

E-mails by Koda Plus

Transactional e-mails for Medusa, sent through Resend, ready the moment you install them: the order confirmation, the shipping e-mail with tracking numbers, the cancellation, the welcome and the password reset, in English and Polish, in your store's look and with a dark mode. Every message is sent once per event, logged with the address masked, and visible in the Medusa admin, where you preview every template live and send yourself a test.

The templates carry no images: the store name is live text and products are tiles with their name, SKU, quantity and price, so nothing breaks when a mail app blocks images. Your own templates (a B2B approval, an invoice, a campaign) plug into the same registry and the same look.

Live demo: Medusa admin medusa.koda.plus/app/emails, signed in to a public demo account by the link itself. The demo runs the plugin in demo mode: every e-mail the store would send lands in a simulated outbox you can open, and nothing leaves the server.

What it does

• Sends the store's e-mails through Resend, as a Medusa notification provider: subscribers to Medusa's events render the right template in the customer's language and hand it to the notification module, the provider sends it.
• Exactly once per event: one idempotency key per event (emails:order.placed:<order id>), checked by Medusa's notification module, claimed atomically in the plugin's send log, and sent to Resend as the Idempotency-Key header.
• Logs what went out with the recipient masked (a***@e***.com): the template, the subject, the status, the Resend id, the error when there was one.
• Shows it in the admin: counters, the log, counts per template, the template gallery with a live preview (light and dark, desktop and phone, Polish and English, sample data or your newest order), a test send, and the e-mails of each order on the order page.

Templates

Wired to Medusa's events, on by default:

• Order confirmation (order.placed, on order.placed): the order's road on a tracker, number, date, delivery, the products with their amounts, the totals with tax and discount notes, the delivery address, a link to the order.
• Order shipped (order.shipped, on shipment.created): every tracking number with its link (from the label, or from your trackingUrls), the products of this parcel, and a note when the rest follows in another parcel.
• Order cancelled (order.canceled, on order.canceled): the order as a slip with its status, the cancelled products, where the money goes.
• Welcome (customer.welcome, on customer.created, registered accounts only): a customer card and three first steps.
• Password reset (password.reset, on auth.password_reset): a button to your storefront's reset page for customers, to the admin's for admin users, how long the link works, what to do if it was not you.

Optional, off until you turn them on:

• Abandoned cart (cart.abandoned, an hourly job): carts idle between 24 and 72 hours with an address and products, one reminder per cart, at most 50 an hour.
• Negotiation e-mails (negotiation.countered, negotiation.accepted, negotiation.rejected): for the events of @koda-plus/medusa-plugin-negotiations when it is installed. The offer with its price per unit (or for the whole cart), the quantity and how long a counter offer is valid. A customer who declines an offer gets no e-mail about their own click. The plugins know each other by event name only; this one has no dependency on that one.

Features

• E-mails page in the admin with three views switched in the header: Panel (what was sent, the template gallery, the test send), Setup guide (also as ?view=guide) and Settings (branding, templates, the provider).
• Live preview of every template, built-in or yours, exactly as the provider renders it, with your branding: light or dark, desktop or phone, Polish or English, on sample data or on your newest order, cart or customer (with the customer's name, company and address replaced by sample ones).
• Test send to an address you type, through the same path as every e-mail, so it also proves the setup. The subject starts with [Test]; at most 5 tests per person in 10 minutes and 30 an hour for the store.
• Branding from the options or from the admin: the store name, a live-text logo (with an accent part such as a "+" and a lighter suffix), the accent and band colours, a footer line per language, a support address. Colours derive the rest: text in the accent colour is darkened or lightened until it reads at 4.5:1, the neutrals take the hue of the band, a band too light for white text is darkened.
• Every template switchable: the option is the hard switch (templates: { key: false }), the admin switch the runtime one, with who flipped it and when.
• Per-recipient language: the order's or cart's locale, then locale or language in the order's, cart's or customer's metadata, then defaultLocale.
• Dark mode for Apple Mail and most apps, Outlook.com included; Polish typography with no one-letter word at the end of a line.
• Under Gmail's clipping size and a plain-text part in every message; long orders show 30 lines and a sum-up line.
• Retry from the admin for failed messages of the order, shipping, cancellation, welcome and cart templates: the data is read again, the provider takes the failed row over, Resend gets a fresh key.
• Order widget on every order page: the e-mails of that order with their status, one click to the message; a host can show it as a tab (see Works with Koda Plus hosts).
• Deep links into the log: /emails?filter=attention&since=7d, /emails?filter=bounced, /emails?order_id=order_..., /emails?customer_id=cus_..., /emails?q=anna@example.com.
• Demo mode (only with demo: true): a simulated outbox, seeded from your newest orders and customers and dated over the last days, rebuilt with fresh dates twice a day so a public demo never looks abandoned; test sends and new events land there and stay; nothing leaves the server, and password reset links are kept hidden.
• Your own templates in the same look, with the same kit, through the templates option or registerEmailTemplate.
• Admin in English and Polish through the Medusa admin translations.

Requirements

• Medusa 2.12 to 2.21 and Node.js 20+ (see Compatibility).
• A Resend account with a verified sending domain, and an API key with sending access. Without a key the plugin logs every message instead of sending it (the admin says "Log only"); in demo mode it needs nothing. The free plan of Resend sends 100 e-mails a day and 3 000 a month: choose a plan for your volume before you go live.

Installation

Yarn and pnpm work the same way: yarn add @koda-plus/medusa-plugin-emails or pnpm add @koda-plus/medusa-plugin-emails.

Configuration

The plugin is registered twice with the same options object: as a plugin (the send log, the admin page, the subscribers and jobs) and as the provider of the email channel in Medusa's notification module (rendering and sending). Keep the object in one constant:

Listing providers replaces Medusa's default list, which held the local provider of the feed channel; that is why the example adds it back. Without it, product import and export and the order export end with "Could not find a notification provider for channel: feed". The admin warns when no provider serves feed.

Set the variables in .env:

Run the migrations, then open E-mails in the admin sidebar:

npx medusa db:migrate

Medusa uses one provider per channel: if another provider serves email (SendGrid, or the local one set to email), remove it, and keep the local one on feed. The admin says when the provider is missing, got other options than the plugin, or runs in another mode. The id of the registration ("emails" above) is the name Medusa's provider table and this admin show; koda-emails is the identifier of the provider class, which you never type.

Options

Sending:

• apiKey: the Resend API key. Without it nothing is sent: every message is rendered, logged and recorded as not sent.
• from: Name <address> or the bare address, on a domain verified in Resend. Required in live mode.
• replyTo: one address or a list. With it, the "Questions?" box tells customers to reply.
• demo (default false): the simulated outbox. Nothing leaves the server, every message is kept to look at. Only demo: true turns it on: a missing API key never does, it means "Log only" (nothing is sent, the admin says what is missing). Set it from a variable of your own, demo: process.env.EMAILS_DEMO === "true".
• requestsPerSecond (default 5), timeoutMs (default 15000), maxRetries (default 2): requests to Resend from one process, the timeout of one request, the extra tries after a temporary error.

Language and links:

• defaultLocale (default "en"): "en" or "pl", when the recipient's language is unknown.
• timeZone (default "UTC"): for dates in messages.
• storefrontUrl: the public address of the storefront. Links default to it: the store, /account, /cart, /reset-password?token={token}&email={email}.
• links: { store, account, order, cart, passwordReset, adminPasswordReset, negotiation }, each an absolute address or a path joined to storefrontUrl, with the placeholders {order_id}, {display_id}, {cart_id}, {country}, {locale}, {token}, {email}, {id}, {ref} (URI-encoded; an empty one leaves no double slash). For example order: "/{country}/account/orders/details/{order_id}".
• adminUrl (default: admin.backendUrl and admin.path of medusa-config.ts): the admin, for the password reset of admin users.
• passwordResetMinutes (default 15): how long the reset link works, for the text of the message (Medusa's own default).
• passwordResetsPerHour (default 3, from 1 to 50): password reset e-mails to one address in any hour. Asking for a reset needs no account, so this keeps a stranger from flooding an inbox from your domain and using up your Resend plan; further requests are logged as skipped (THROTTLED).
• trackingUrls: tracking links per fulfillment provider id (or its first part) when a label has none, e.g. { inpost: "https://inpost.pl/sledzenie-przesylek?number={number}" }.

Brand (brand), each field also editable in the admin:

• name: in subjects and texts.
• logo: { text, accent, suffix, italic }, the logo as live text (default: the name).
• accentColor (default #26D07C), headerColor (default #212721): buttons and highlights, and the band at the top.
• footer: one line, a string or { en, pl }.
• supportEmail: shown in the "Questions?" box.
• headingFont, bodyFont: CSS font-family lists (default: the system sans). fontFaces: [{ family, url }], web fonts on https, loaded where the mail app allows them.

Templates:

• templates: false turns a template off for good (the admin cannot turn it on), true turns an optional one on, a definition adds a template or replaces a built-in one under its key.
• abandonedCart: { afterHours: 24, maxAgeHours: 72, maxPerRun: 50 }. The links of links.cart lead to the cart: with {cart_id} in it, the link opens that cart (and the address typed in it) for anyone who holds the e-mail, so prefer a page that asks the shopper to sign in.
• skipOrderMetadataKeys (default ["marketplace_order_ref"]): orders with one of these metadata keys get no e-mail. Orders with Medusa's no_notification never do. A shopper cannot set these keys through the Store API (see Security).
• negotiationAmounts (default "major"): only for negotiation events that send price as a number without price_amount, in major units (469 for 469.00) or minor (46900). The Koda Plus negotiations plugin sends price as a decimal string and price_amount in minor units, so it needs nothing here.

Presentation and data:

• logRetentionDays (default 365, 0 keeps everything): how long the send log keeps its rows.
• references (default none): stores running the plugin, shown as "Running in production": [{ name, url, description?, metrics?: [{ label, value }], links?: [{ label, url }], soon? }], texts plain or { en, pl }. soon: true marks a store that starts on Medusa soon: it is shown with a "Soon" badge and no link, and its url is optional. Entries without a name, or live entries without an https URL, are dropped.

Missing or broken options never break the boot: broken values fall back to their defaults and the admin lists them.

Custom templates

A template is a definition with a render function. Build it with the kit to get the look, the dark mode, the escaping and the plain-text part for free, then pass it in templates (in the shared options object, so the plugin and the provider both get it):

Then send it from your own code, through the notification module or the bundled workflow:

• The kit: inline text (accent, strong, nowrap, mono, muted, link, br) and blocks: paragraph, section, facts, items, totals, steps, checks, note, actions, linkFallback, tracking, priceList, divider, and on the band tracker, card, slip, tiles. Strings are escaped; only trusted(html, text) passes markup through.
• render may also return finished { subject, html, text? }; the text part is then made from the HTML.
• Keep render pure: the same data, the same message. A retry must send the same payload.
• sensitive: ["field"] marks data fields that carry a secret (a link with a token, as reset_url of the built-in password reset). Such a message never goes through Medusa's notification table (the plugin hands it to its provider directly, with the same send log and idempotency), and the simulated outbox keeps it with those fields hidden. A built-in template you replace under its key keeps its secret fields.
• registerEmailTemplate(key, definition) registers at run time instead (from a file Medusa loads in every process). Lookup order: the templates option, then registerEmailTemplate, then the built-in set.
• renderEmailPreview({ template, data, locale, options }) renders outside Medusa, for your own tests.
• A notification whose provider_data.emails.kind is "test" ignores the template switches: that is how the admin's test send checks a template that is off. Keep it for tests.
• App code may call createNotifications({ to, channel: "email", template, data }) directly; pass an idempotency_key to make it exactly once. Medusa keeps data in its notification table and returns it from GET /admin/notifications, so send a template with secret fields through sendEmailWorkflow instead.

Setup in brief

The admin has the full guide (E-mails, Setup guide), with the state of every step taken from your store.

1. Create a Resend account. Until a domain is verified, Resend sends only from its own test address and only to the address of your account. The free plan sends 100 e-mails a day and 3 000 a month.
2. Add your sending domain in Resend (a subdomain such as mail.example.com keeps your main domain's reputation apart) and add the records it shows at your DNS provider: MX and TXT (SPF) on send, TXT (DKIM) on resend._domainkey. Add DMARC on the main domain.
3. Create an API key with sending access, limited to that domain, and put it in the environment.
4. Install the plugin, register it as a plugin and as the email provider with the same options (with Medusa's local provider kept on feed), run the migrations.
5. Set the branding and point the links at your storefront, the password reset page included.
6. Send a test of the order confirmation to yourself; look at it on a phone and in dark mode.
7. Choose the templates: turn off what another system sends, turn on the optional ones you want.
8. Place and ship a real order; watch the Failed counter for the first days. Choose a Resend plan that covers your busiest day before it comes.

Security and data

• The API key travels only in the Authorization header to api.resend.com. It is never sent to the admin (which sees "set" or "missing"), and it is masked, with every re_... key, Bearer value and long token, in logs, stored errors and admin screens.
• Password reset links never sit in a table. The reset e-mail does not go through Medusa's notification module, whose table keeps the data of every notification and returns it from GET /admin/notifications to every admin user and secret API key; the plugin hands it straight to its provider (the same send log, switch and idempotency key). The send log keeps a hash of the token in the key, never the token; the simulated outbox of demo mode keeps the message with the link hidden, and demo mode handles no reset of an admin user. Without the provider registered in the process, a reset is not sent at all.
• At most passwordResetsPerHour (3) reset e-mails per address in an hour, counted in the send log under a lock per address, so several processes never pass the limit together.
• Addresses are masked in logs and in the send log (a***@e***.com). Next to the masked address the log keeps a one-way hash of the address (to find the e-mails of one address and to count resets) and the Medusa customer id. It keeps the template, the subject, the status, the Resend id and ids of the order or customer; never the message body (except in demo mode, for the simulated outbox, with secret fields hidden).
• Escaping by construction: every value from customers, the catalog and the configuration is escaped in the HTML; links are used only when they are absolute http(s) addresses; colours and fonts from the options are validated before they reach CSS. The admin preview runs in a sandboxed frame without scripts.
• A stranger's words stay out of the welcome. Anyone can register with any address, and Medusa does not confirm it: the welcome shows a name only when it reads like one (letters, spaces, apostrophes, hyphens), a company only when it is not a link, an address or a domain, and the subject carries no name at all.
• Previews and tests never carry a customer's details: with your newest order they keep the products, amounts and the order number, and replace the name, company, address, the order and cart ids and the tracking numbers with sample ones (a real cart id opens the cart, with the shopper's address, through the Store API).
• Test sends are limited (5 per person in 10 minutes, 30 an hour for the store), counted in the send log as well as in memory, so a restart or a second instance does not reset them, and logged with who sent them.
• The demo outbox shows the sample person: the store's products, amounts and numbers with the name, address and tracking numbers of the samples, so a demo on a copy of a live database never keeps customers' details.
• Writes need the admin. Writes to /admin/emails/* (settings, test sends, retries, the demo seed) take a JSON body or the x-koda-request header and answer 415 otherwise: Medusa's session cookie is SameSite=None in production, so a form on another site could otherwise post with it. The plugin's admin sends both.
• Shopper metadata is not state. A shopper may not set the keys of skipOrderMetadataKeys on a cart or the account through the Store API (400 reserved_metadata_key): Medusa copies cart metadata to the order, and such an order gets no e-mail. The language keys (locale, language) stay the shopper's own.
• Reads do not write: GET routes only read; the demo outbox is built by POST /admin/emails/demo/seed (the page asks for it) and by the hourly housekeeping job.
• Errors: unexpected server errors answer a plain sentence; the details stay in the server log, masked.
• No retry storms: only temporary answers are tried again, at most twice, with the same idempotency key; a breaker stops retrying during an outage; quotas, auth and validation errors are final. A message whose fate is unknown is never resent by itself.
• When the settings cannot be read, the last settings this process read stay in force; with none, nothing is sent and the message is logged as failed (SETTINGS_UNAVAILABLE) for a person to retry. A template switched off in the admin never comes back on by itself.
• Demo negotiations (demo: true in the event) never e-mail anyone outside demo mode.
• What Medusa itself keeps: the notification table of Medusa keeps the address and the data of every notification (names, order lines, links) with no end date; the retention of this plugin covers only its own send log. Messages the plugin skips (a template switched off, no API key, a duplicate) are success there, without an external id: the send log of this page tells what really happened.
• The send log deletes its own rows after logRetentionDays; nothing in Medusa is changed by this plugin (no cart or order metadata is written).

What this plugin does not do

• It does not send staff notifications (a new order for the team), newsletters or marketing campaigns; the abandoned cart reminder is the only one, off by default, and it adds no unsubscribe link: check your consent basis before you turn it on.
• It does not attach invoices or other files by itself; attachments passed to the notification module are sent along.
• It does not read Resend's delivery, open or bounce events (webhooks): the log says what Resend accepted, not what reached the inbox.
• It does not manage Resend domains, API keys or audiences.
• It does not send SMS or push messages, only the email channel.
• It does not translate your custom templates: they render what you write, in the languages you write.

Works with Koda Plus hosts

An app that shows every Koda Plus plugin in one place (like medusa.koda.plus) reads E-mails through the shared contract koda.integration/1 and never needs to know its tables:

• GET /admin/emails/integration: the manifest (mode, configuration, problems such as no API key or a provider that is not registered, the widget).
• GET /admin/emails/integration/summary?entity=order&id=order_... (or ids=, up to 50; entity=customer too): one line per record, the worst message speaking. A message that failed is red; one that may not have gone out, or an address that was refused (customers), is orange; one being sent is blue; sent is green, with the number of messages and the newest one. Messages skipped on purpose (a template switched off, no API key) only speak when there is nothing else, and test sends never count. A customer's line covers the customer's own e-mails and those of orders placed as a guest with the same address (found by the hash of the address). No facts: e-mails are not a payment, a delivery or a document.
• GET /admin/emails/integration/attention?scope=orders,customers: counters of the last 7 days, messages_failed (red, orders: messages of orders that failed or may not have gone out, linked to /emails?filter=attention&since=7d) and bounced (orange, customers: addresses refused when a message was sent, linked to /emails?filter=bounced&since=7d). The plugin reads no bounce webhooks of Resend, so a message that bounced after Resend accepted it is not counted.
• The order card registers as emails.order for the zone order.details (tab order 80); a host that claims the zone shows it as a tab (embedded) and Medusa's own spot stays empty. Without a host nothing changes.
• The page opens on deep links: ?filter= (all, sent, attention, skipped, test, bounced), ?since= (24h, 7d, 30d), ?order_id=, ?customer_id= and ?q=.

All three routes only read the send log (and, for a customer, the customer's address by id); they never seed the demo outbox, call Resend or write.

Public API

What other code may import: @koda-plus/medusa-plugin-emails/templates (your own templates: defineEmailTemplate, registerEmailTemplate, the kit, renderEmailPreview, the data types), @koda-plus/medusa-plugin-emails/workflows (sendEmailWorkflow, sendAbandonedCartsWorkflow, sendTemplate, emailsIntegration), @koda-plus/medusa-plugin-emails/modules/emails (the module, its options and the same template API), @koda-plus/medusa-plugin-emails/providers/emails (the notification provider) and /admin. Type declarations ship with the package, so defineEmailTemplate<{ ... }>(...) is checked in a strict TypeScript app. Every other path is internal and may change in any release.

Uninstall

1. Remove both registrations from medusa-config.ts: the plugin in plugins, and its provider in the notification module. Put back a provider for the email channel if the store still sends e-mails, and keep the local provider on feed (or remove the whole @medusajs/medusa/notification entry to go back to Medusa's defaults).
2. Remove the package from package.json.
3. The tables emails_message and emails_setting stay with their data. Drop them by hand when you no longer need the log, or run npx medusa db:rollback emails before removing the package. Medusa keeps its own notification rows and the record of the migrations; the emails row of its provider table is disabled by Medusa once the provider is gone.

Compatibility

Medusa 2.12 to 2.21 (peer range ^2.12.0) and Node.js 20+. The tests and the build run on Medusa 2.15.3; the release of each version runs the smoke test on a fresh Medusa 2.12.6 and 2.21.2 app (migrations, build, start and the admin pages). Admin translations need Medusa 2.12 or newer. Developing the plugin needs Node.js 22.6+ (the tests run the TypeScript sources directly).

Development

npm test covers every built-in template in both languages (with full and with almost no data, escaping, the clipping size, dark mode, the text part), the delivery path of the provider (dev mode, demo mode, the exact Resend request, idempotency, switches, finished content, failures, a person's retry, a missing table), the Resend client (error mapping, retries with the same key, retry-after, the breaker, pacing), options, links, locales and formats, masking, keys, the registry and app templates, settings, the SQL of the send log, the mappers from Medusa records, and the flows with a fake Medusa container. Tests need Node.js 22.6 or newer (they run the TypeScript sources directly). What the plugin relies on from the Resend and Medusa documentation is in docs/resend-api-notes.md. To try the plugin in a Medusa app, run npx medusa plugin:publish here, then npx medusa plugin:add @koda-plus/medusa-plugin-emails in the app.

Commercial support

Built and maintained by Koda Plus, a Medusa agency from Poland. The templates grew out of the e-mails of our Medusa demo store and the stores we build. Need your own templates, another provider or a Medusa store? Write to kontakt@koda.plus.

Trademarks

Resend is a trademark of its owner, used here only to identify the e-mail service this plugin sends through. This is an independent integration built on the public Resend API, not affiliated with or endorsed by Resend.

License

MIT, see LICENSE.

Changelog

Every release is in CHANGELOG.md. Version 0.2.0 keeps password reset links out of every table, limits resets per address, adds the contract for Koda Plus hosts (summaries of orders and customers, board counters, the order card as a tab) and ships type declarations; it needs npx medusa db:migrate.