Notification postal
Провайдер уведомлений Postal для Medusa
@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
Options
- - Postal API mode
- - default sender e-mail address
Postal API settings
- - Postal base URL, for example
- - Postal server API key used in
only accepts (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:
| Variable | Secret | Purpose |
|---|---|---|
| no | Auth mode; only is supported (default ). | |
| no | Default sender address ( option). | |
| no | Postal base URL ( option). Must be /. | |
| yes | Postal server API key ( option). | |
| yes | Shared secret in the tokenized webhook path; generated if unset. | |
| no | Outbound Postal HTTP timeout in ms (default ). | |
| no | Default recipient for admin test sends. | |
| no | JSON overriding the built-in template registry. | |
| no | Comma-separated template display order. | |
| no | Overrides the tag prefix used to correlate webhook callbacks. | |
| no | Overrides the webhook events table name. | |
| no | Overrides the notification provider id. | |
| no | Overrides the plugin module registration name. |
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 (, , ) persist in the table via the plugin module — run after installing. Secrets (, ) 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 :
The provider logs and 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:
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:
| Template | Purpose | Typical Medusa event | Notes |
|---|---|---|---|
| Generic fallback preview | Any custom template name | Used when no registry match exists and content is incomplete. | |
| Provider transport validation | Used for operator sends and transport checks. | ||
| Admin settings validation | Used by the admin test-send form. | ||
| Customer order confirmation | Shared transactional order mail. | ||
| Native Medusa Admin invitation | , | Use application-rendered content so the environment-specific invite URL is delivered without logging the token. | |
| Account password reset | Shared auth email template. | ||
| Account email verification | Shared auth email template. | ||
| Customer onboarding | Shared onboarding and first-contact template. | ||
| Cart recovery | Shared recovery reminder template. | ||
| Back-in-stock alert | 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 and :
are normalized into safe email headers for transport-level traceability. 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 , , and custom 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:
formats the sender as . 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 . This ensures the mail goes through the provider's standard channel and logs full delivery metadata.