Notification 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: MIT
• Changelog: CHANGELOG.md

Options

• auth_type - Postal API mode
• from - default sender e-mail address

Postal API settings

• base_url - Postal base URL, for example https://postal.example.com
• api_key - Postal server API key used in X-Server-API-Key

auth_type only accepts smtp-api (the Postal HTTP API); any other value is rejected at startup.

Environment variables

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

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

Settings persistence

Non-secret settings edited in the admin (from, base_url, test_to) persist in the postal_setting table via the plugin module — run medusa db:migrate after installing. Secrets (POSTAL_API_KEY, POSTAL_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.

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:

Workflow tracking

Use Medusa notification workflows and pass workflow metadata in provider_data:

The provider logs workflow_event and workflow_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 is shown in the Postal admin activity page after you save settings. 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:

• MessageSent
• MessageDelayed
• MessageDeliveryFailed
• MessageHeld
• MessageBounced
• MessageLinkClicked
• MessageLoaded
• DomainDNSError

Incoming webhook payloads are stored as raw JSON with normalized status metadata, so you can inspect delivery state changes in the admin Postal page after Postal calls back into Medusa.

The admin page also shows a webhook event log and the endpoint to configure inside Postal.

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.

Template registry and metadata passthrough

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

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 provider_data.metadata and provider_data.custom_args:

custom_args are normalized into safe email headers for transport-level traceability. metadata 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 cc, bcc, and custom headers 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:

from_name formats the sender as Name <email>. reply_to is forwarded to Postal and preserved in provider data.

Programmatic Workflows

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