Overview
Icon for Postal Notifications

Postal Notifications

Send transactional emails through Postal

@uhlhosting/medusa-notification-postal

A production-ready Postal notification provider for Medusa. Designed for reliable transactional email delivery through Postal's HTTP API, strong configuration validation, template-based workflows, and seamless integration with Medusa’s notification system.

Release

  • Current package version:
  • License: Copy to clipboardMIT
  • Changelog: Copy to clipboardCHANGELOG.md

Options

The package has two sets of options: the provider options, under the Notification Module, and the plugin options, on the Copy to clipboardplugins entry. See Usage for where each goes.

Provider options

  • Copy to clipboardauth_type - Postal API mode
  • Copy to clipboardfrom - default sender e-mail address
  • Copy to clipboardbase_url - Postal base URL, for example Copy to clipboardhttps://postal.example.com
  • Copy to clipboardapi_key - Postal server API key used in Copy to clipboardX-Server-API-Key
  • Copy to clipboardrequest_timeout_ms - outbound Postal HTTP timeout in ms. Optional. It takes precedence over Copy to clipboardPOSTAL_REQUEST_TIMEOUT_MS, falls back to that variable and then to Copy to clipboard10000, and is clamped to 1000-60000.

Copy to clipboardauth_type only accepts Copy to clipboardsmtp-api (the Postal HTTP API); any other value is rejected at startup.

Plugin options

Every plugin option is off unless you set it, so upgrading changes nothing for a store that does not configure them.

Option Default Effect Copy to clipboardnotification_retention_days unset (off) A daily job (Copy to clipboardpostal-purge-expired-notifications, 03:30) hard-deletes every row in Medusa's core Copy to clipboardnotification table created more than this many days ago, whatever its provider, channel, template, resource or status. Copy to clipboardwebhook_event_retention_days unset (off) A daily job (Copy to clipboardpostal-purge-webhook-events, 03:40) hard-deletes redacted Copy to clipboardpostal_webhook_events delivery metadata created more than this many days ago. Recipient addresses and raw Postal payloads are never retained. Copy to clipboardignore_engagement_webhooks Copy to clipboardfalse Copy to clipboardMessageLinkClicked and Copy to clipboardMessageLoaded callbacks are acknowledged but neither stored nor emitted as Copy to clipboardpostal.clicked / Copy to clipboardpostal.loaded. Delivery outcomes (sent, delayed, failed, held, bounced, DNS errors) are still recorded.

The retention options take a whole number of days from 1 to 7300, as a number or a numeric string. Any other value leaves that purge off, and the job logs a warning that names the option but not the value. Job schedules are fixed in the job files; the periods are read from the plugin module at run time. The jobs log counts and cutoffs only, never recipients or content.

Webhook purge additionally requires a published receipt with no publication owner or lease expiry. Unpublished work and any lease metadata survive regardless of age, including expired or inconsistent leases, so retention cannot discard recoverable delivery work. Investigate unresolved receipts rather than deleting them to force progress. Published, unleased metadata retains the configured creation-time cutoff; notification retention is unchanged. Approve the replay horizon before enabling callback retention.

Copy to clipboardnotification_retention_days is deliberately provider-neutral. The Copy to clipboardnotification table is shared by every notification provider in the store, and each row is delivery metadata (recipient, template, provider message id, sometimes a Reply-To address) with no retention of its own. Before you set it, check that nothing in your store relies on old rows: a notification Copy to clipboardidempotency_key only deduplicates while its row exists.

Environment variables

The provider options above are typically wired from environment variables. The plugin also reads the following at runtime:

Variable Secret Purpose Copy to clipboardPOSTAL_AUTH_TYPE no Auth mode; only Copy to clipboardsmtp-api is supported (default Copy to clipboardsmtp-api). Copy to clipboardPOSTAL_FROM no Default sender address (Copy to clipboardfrom option). Copy to clipboardPOSTAL_BASE_URL no Postal base URL (Copy to clipboardbase_url option). Must be Copy to clipboardhttp/Copy to clipboardhttps. Internal self-hosted DNS names are supported; Copy to clipboardlocalhost and literal private, loopback or link-local IP addresses are rejected before a request. Credentials/query/fragment and redirects are forbidden; restrict configuration access and egress. Copy to clipboardPOSTAL_API_KEY yes Postal server API key (Copy to clipboardapi_key option). Copy to clipboardPOSTAL_WEBHOOK_TOKEN yes Shared secret in the tokenized webhook path. Required for webhooks and not generated: until it is set the webhook route rejects every call and the admin shows no callback URL. Copy to clipboardPOSTAL_WEBHOOK_PUBLIC_KEY no Postal's RSA public key (PEM, JWK, or the single-key JWKS from Copy to clipboard/.well-known/jwks.json). When set, webhooks must also carry a valid Postal signature. Copy to clipboardPOSTAL_REQUEST_TIMEOUT_MS no Outbound Postal HTTP timeout in ms (default Copy to clipboard10000, clamped to 1000-60000). The Copy to clipboardrequest_timeout_ms provider option wins when set. The deadline includes body consumption and responses are capped at 1 MiB. Copy to clipboardPOSTAL_TEST_TO no Recipient for admin test sends, and the address sandbox mode redirects to. Copy to clipboardPOSTAL_SANDBOX no Copy to clipboardtrue redirects every recipient to Copy to clipboardPOSTAL_TEST_TO (see Sandbox mode). Off unless set. Copy to clipboardMEDUSA_BACKEND_URL no Origin for the absolute webhook callback URL shown in the admin (Copy to clipboardVITE_BACKEND_URL is the fallback). Request Copy to clipboardOrigin/Copy to clipboardHost/Copy to clipboardX-Forwarded-* headers are never used for it.

No other variables are read. The template registry, the webhook tag prefix (Copy to clipboarduhlhosting.medusa-notification-postal:), the webhook events table (Copy to clipboardpostal_webhook_events), the provider identifier (Copy to clipboardnotification-postal) and the module name (Copy to clipboardpostalPlugin) are fixed in code and cannot be overridden from the environment.

Keep the secret variables out of logs and client-visible surfaces; the admin settings endpoint never returns them.

Sandbox mode

A staging or preview deployment sends the same mail a production one does — order confirmations, quotes, contact enquiries — to the same real customers. Set Copy to clipboardPOSTAL_SANDBOX=true there and every recipient is replaced by Copy to clipboardPOSTAL_TEST_TO instead:

  • Copy to clipboardto, Copy to clipboardcc and Copy to clipboardbcc all collapse to the single sandbox address, so nobody else is written to.
  • The original addresses are preserved in Copy to clipboardX-Postal-Sandbox-To, Copy to clipboard-Cc and Copy to clipboard-Bcc, alongside Copy to clipboardX-Postal-Sandbox: true. These are applied after the caller's own headers, so a notification cannot forge or overwrite them.
  • The subject is prefixed with the address it was meant for — Copy to clipboard[sandbox: customer@example.com +3] Ihre Bestellung — because one inbox now receives mail addressed to many different people, and the subject is the only part of that a mailbox list shows.

The switch is explicit and off by default, for two reasons:

  • Copy to clipboardNODE_ENV cannot stand in for it. A typical Medusa container image sets Copy to clipboardNODE_ENV=production in its runtime stage, so staging, preview and production are all "production" to the running process and the value carries no signal.
  • Neither can the presence of Copy to clipboardPOSTAL_TEST_TO. Production sets that too — it is the recipient of the admin's send test email button — so defaulting to on would turn one forgotten variable in production into every customer's order confirmation landing in an internal test inbox. Silently swallowing real mail is a worse failure than the one sandbox mode prevents, so it fails closed.

If sandbox mode is on but Copy to clipboardPOSTAL_TEST_TO is empty, the provider logs the misconfiguration once and sends as addressed; refusing would leave the environment unable to send anything at all.

Settings persistence

Non-secret settings edited in the admin (Copy to clipboardfrom, Copy to clipboardbase_url, Copy to clipboardtest_to) persist in the Copy to clipboardpostal_setting table via the plugin module — run Copy to clipboardmedusa db:migrate after installing. Secrets (Copy to clipboardPOSTAL_API_KEY, Copy to clipboardPOSTAL_WEBHOOK_TOKEN) are sourced from the environment/provider options only, are read-only in the admin UI, and are never written to disk. Changes that affect the constructed provider take effect after a backend restart. Configure Notification Copy to clipboarddependencies: ["postalPlugin"] as below. The module captures an immutable boot snapshot and applies the saved sender only when the saved destination exactly matches the operator-approved provider URL. Changing destinations requires updating host configuration and restarting; a mismatch blocks the provider before any request and retains the pending flag. The first provider send acknowledges only the exact saved revision applied, so later admin edits remain pending until another restart. No global environment variables are changed. Using the provider alone without the Postal plugin is an environment/options-only configuration and has no persisted settings contract. Clearing a field in the admin removes its saved override, so after the restart the value comes from the matching environment variable again; until then the admin shows a restart notice.

Usage

Register the plugin package so its module, migrations, routes, and Admin extension are loaded. Then register the explicit Postal provider subpath under the Notification Module:

module.exports = defineConfig({
plugins: [
{
resolve: "@uhlhosting/medusa-notification-postal",
// Plugin options; all optional and off by default.
options: {
notification_retention_days: 90,
webhook_event_retention_days: 90,
ignore_engagement_webhooks: true,
},
},
],
modules: [
{
resolve: "@medusajs/medusa/notification",
dependencies: ["postalPlugin"],
options: {
providers: [
{
resolve:

Admin extension and package managers

The Postal admin pages run inside the Medusa dashboard and share its copies of Copy to clipboard@tanstack/react-query, Copy to clipboardreact-router-dom, Copy to clipboardi18next and Copy to clipboardreact-i18next. The plugin declares them as peer dependencies and each must resolve to the same installed copy the dashboard uses.

  • npm / yarn: nothing to do; the dashboard's copies are hoisted and satisfy the peer ranges.
  • pnpm: two project-level settings are needed, otherwise the admin fails to start or the Postal pages crash with Copy to clipboardNo QueryClient set, use QueryClientProvider to set one.
    1. Hoist the dashboard's packages (pnpm 10+ reads this from Copy to clipboardpnpm-workspace.yaml; the Copy to clipboardpublic-hoist-pattern lines in a starter's Copy to clipboard.npmrc are no longer honoured):
publicHoistPattern:
- "*@medusajs/*"
- "@tanstack/react-query"
- react-i18next
- react-router-dom
  1. Pin the four shared packages to the versions the dashboard ships. pnpm installs a plugin's peer dependencies at the newest version in range, which is not the dashboard's, so without direct pins the plugin gets its own copy of each: Copy to clipboardreact-router-dom breaks the "Open activity page" link (Copy to clipboardCannot destructure property 'basename'), Copy to clipboard@tanstack/react-query breaks every page (Copy to clipboardNo QueryClient set), and Copy to clipboardi18next/Copy to clipboardreact-i18next leave labels showing raw translation keys. Print the dashboard's versions, then add them as direct dependencies: Copy to clipboardpnpm list react-router-dom should then show a single version. Repeat after every Medusa upgrade.
node -e "const m=require.resolve('@medusajs/medusa/package.json');const d=require(require.resolve('@medusajs/dashboard/package.json',{paths:[m]}));console.log(['@tanstack/react-query','react-router-dom','i18next','react-i18next'].map(n=>n+'@'+d.dependencies[n]).join(' '))"
pnpm add @tanstack/react-query@<v> react-router-dom@<v> i18next@<v> react-i18next@<v>

Workflow tracking

Use Medusa notification workflows and pass workflow metadata in Copy to clipboardprovider_data:

await notificationModuleService.createNotifications({
channel: "email",
to: "cosmin@example.com",
template: "order-placed",
content: {
subject: "Order confirmation",
html: "<p>Thanks for your order</p>",
text: "Thanks for your order",
},
provider_data: {
workflow_event: "order.placed",
workflow_run_id: "wf_run_123",
},
})

The provider logs Copy to clipboardworkflow_event and Copy to clipboardworkflow_run_id for traceability in Medusa runtime logs.

Postal Webhooks

The plugin now exposes a public ingestion endpoint for Postal delivery lifecycle webhooks:

POST /postal/webhooks/<postal-webhook-token>

The exact tokenized URL (with a copy button) is shown on the Postal admin activity page once Copy to clipboardPOSTAL_WEBHOOK_TOKEN is set. The absolute callback URL is built only from a configured backend origin (Copy to clipboardMEDUSA_BACKEND_URL, then Copy to clipboardVITE_BACKEND_URL) — request headers are never trusted for it, and when no origin is configured only the callback path is shown. The settings screen intentionally only shows the callback path so the secret stays out of the configuration surface.

It accepts the Postal message status events documented by Postal:

  • Copy to clipboardMessageSent
  • Copy to clipboardMessageDelayed
  • Copy to clipboardMessageDeliveryFailed
  • Copy to clipboardMessageHeld
  • Copy to clipboardMessageBounced
  • Copy to clipboardMessageLinkClicked
  • Copy to clipboardMessageLoaded
  • Copy to clipboardDomainDNSError

Postal delivers each webhook as an envelope, Copy to clipboard{ "event", "timestamp", "payload", "uuid" }, with the documented message data under Copy to clipboardpayload. The route reads that envelope (a flat body is also accepted). Message delivery events are recorded only when the message carries this plugin's tag (Copy to clipboarduhlhosting.medusa-notification-postal:<template>, added to every send), so mail sent by other applications on the same Postal server is ignored. Copy to clipboardDomainDNSError has no message tag and is recorded as a server-wide event. Recording is idempotent per callback: a replayed callback is acknowledged without a second row. Only allowlisted metadata enters workflow state; recipients and raw callbacks do not.

Only normalized delivery metadata is stored (event type, status, provider message ID and timestamps), never the raw callback, so you can follow delivery state changes in the admin Postal page after Postal calls back into Medusa.

The admin page shows a redacted webhook activity log and the endpoint to configure inside Postal. It exposes event type, status, provider message ID, and timestamps only - never recipients or raw callbacks.

Postal's HTTP payload docs are separate from webhook delivery callbacks and are mainly useful if you are also handling inbound mail by HTTP. Postal's auto-responder, bounce, wildcard, and address-tag docs are relevant when you want to route inbound mail or reason about delivery replies, but they do not change the webhook callback contract itself.

Signature verification (optional)

The URL token is always required. To also verify that each webhook really came from your Postal installation, set Copy to clipboardPOSTAL_WEBHOOK_PUBLIC_KEY to Postal's public signing key. Fetch it without authentication from Copy to clipboardhttps://<postal-host>/.well-known/jwks.json and paste the JSON as-is, or paste the key as PEM. On the Postal host, Copy to clipboardpostal default-dkim-record also prints it: wrap the Copy to clipboardp= value in Copy to clipboard-----BEGIN PUBLIC KEY----- / Copy to clipboard-----END PUBLIC KEY----- lines. PEM with literal Copy to clipboard\n escapes (single-line env files) is accepted.

When the key is set, the plugin verifies the signature over the exact raw request body:

  • Copy to clipboardX-Postal-Signature-256 (RSA SHA256, Postal ≥ 3.2) is checked whenever present. A failed SHA256 check is never retried with SHA1.
  • Copy to clipboardX-Postal-Signature (RSA SHA1, legacy Postal 2.x) is used only when the SHA256 header is absent.
  • Requests with a missing or invalid signature are rejected with Copy to clipboard400. An unparseable key fails closed: every token-authenticated webhook gets a Copy to clipboard500 and the backend log says why.

Leave the variable unset to rely on the URL token alone.

Template registry and metadata passthrough

The plugin includes a built-in template registry for common notification flows:

Template Purpose Typical Medusa event Notes Copy to clipboarddefault Generic fallback preview Any custom template name Used when no registry match exists and content is incomplete. Copy to clipboardpostal-test Provider transport validation Copy to clipboardpostal.example.test Used for operator sends and transport checks. Copy to clipboardpostal-admin-test Admin settings validation Copy to clipboardadmin.postal.test Used by the admin test-send form. Copy to clipboardorder-placed Customer order confirmation Copy to clipboardorder.placed Shared transactional order mail. Copy to clipboardadmin-invite Native Medusa Admin invitation Copy to clipboardinvite.created, Copy to clipboardinvite.resent Use application-rendered content so the environment-specific invite URL is delivered without logging the token. Copy to clipboardpassword-reset Account password reset Copy to clipboardcustomer.password_reset Shared auth email template. Copy to clipboardemail-verification Account email verification Copy to clipboardcustomer.email_verification Shared auth email template. Copy to clipboardwelcome Customer onboarding Copy to clipboardcustomer.welcome Shared onboarding and first-contact template. Copy to clipboardabandoned-cart Cart recovery Copy to clipboardcart.abandoned Shared recovery reminder template. Copy to clipboardrestock-available Back-in-stock alert Copy to clipboardrestock.available Shared inventory alert template.

If a template key is not in the registry, Postal still uses the provided template string and falls back to the passed content. You can also pass extra tracing data through Copy to clipboardprovider_data.metadata and Copy to clipboardprovider_data.custom_args:

provider_data: {
subject: "Order confirmation",
html: "<p>Thanks for your order</p>",
text: "Thanks for your order",
workflow_event: "order.placed",
workflow_run_id: "wf_run_123",
metadata: {
store: "main",
environment: "production",
},
custom_args: {
order_id: "ord_123",
customer_group: "vip",
},
}

Copy to clipboardcustom_args are normalized into safe email headers for transport-level traceability. Copy to clipboardmetadata stays available in Medusa-side notification data and logs.

The admin Postal settings page uses the same registry for test-send template selection, so the built-in examples stay aligned across the backend and admin UI. The selected template also shows a preview of its subject, text, and HTML in the admin test-send panel. That panel also includes a full example payload with recipient, sender identity, workflow metadata, and sample custom args for the selected template. The same panel now lets you load the example values into the test form with one click, edit the message subject/text/HTML/custom args/metadata, or copy the example JSON directly. It also exposes Copy to clipboardcc, Copy to clipboardbcc, and custom Copy to clipboardheaders so test sends match the provider contract more closely.

You can also set sender identity fields when you need branded mail or a separate reply path:

provider_data: {
from: "no-reply@example.com",
from_name: "Postal Admin",
reply_to: "support@example.com",
cc: "billing@example.com",
bcc: ["archive@example.com"],
headers: {
"X-Trace-Id": "trace_123",
},
}

Copy to clipboardfrom_name formats the sender as Copy to clipboardName <email>. Copy to clipboardreply_to is forwarded to Postal as both the Copy to clipboardreply_to field and the Copy to clipboardReply-To header when it is exactly one bare printable-ASCII address (surrounding whitespace is trimmed). Anything else (a display name, a list, CR/LF, non-ASCII or invisible characters) is dropped and a warning is logged that names no address; the message is still sent, without a reply path. A Copy to clipboardReply-To entry in Copy to clipboardprovider_data.headers (in any letter case) gets the same check and is dropped the same way when it is not one plain address. When Copy to clipboardreply_to is valid it replaces any such header, and at most one Copy to clipboardReply-To is sent. This makes it safe to pass a customer-supplied address, such as a contact-form enquirer's, either way.

Programmatic Workflows

You can trigger a direct email notification through the Postal provider programmatically using the Copy to clipboardsendPostalEmailWorkflow. This ensures the mail goes through the provider's standard channel and logs full delivery metadata.

import { sendPostalEmailWorkflow } from "@uhlhosting/medusa-notification-postal"
const { result } = await sendPostalEmailWorkflow(req.scope).run({
input: {
to: "cosmin@example.com",
from: "custom-sender@example.com", // Optional, defaults to POSTAL_FROM
template: "custom-template-id", // Optional
provider_data: {
subject: "Test Programmatic Email",
html: "<p>Hello, this is a test email sent programmatically.</p>",
text: "Hello, this is a test email sent programmatically.",
cc: "billing@example.com",
workflow_event: "admin.test_send",
workflow_run_id: "wf_run_manual_123"
}
}
})
// Result returns the delivery info:
// { success: true, delivery: { message_id: "123", ... } }

Production migration

Medusa 2.22.6/UI 4.2.13 and the callback replay/publication migration are required. See migration and deployment gates before upgrading server/worker processes.

You may also like

Browse all integrations

Build your own

Develop your own custom integration

Build your own integration with our API to speed up your processes. Make your integration available via npm for it to be shared in our Library with the broader Medusa community.

gift card interface

Ready to build your custom commerce setup?