Postal Notifications

@uhlhosting/medusa-notification-postal

A production-ready Postal notification provider for Medusa. Designed for reliable transactional email delivery, 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

• Copy to clipboardauth_type - one of Copy to clipboardsmtp-api, Copy to clipboardsmtp-ip, Copy to clipboardsmtp (default Copy to clipboardsmtp-api)
• Copy to clipboardfrom - default sender e-mail address

Copy to clipboardsmtp-api options

• Copy to clipboardbase_url - Postal base URL, for example Copy to clipboardhttps://post.example.com
• Copy to clipboardapi_key - Postal server API key used in Copy to clipboardX-Server-API-Key

Copy to clipboardsmtp-ip options

• Copy to clipboardsmtp_host - Postal SMTP host
• Copy to clipboardsmtp_port - SMTP port, default Copy to clipboard25
• Copy to clipboardsmtp_secure - Copy to clipboardtrue for TLS, default Copy to clipboardfalse
• Copy to clipboardsmtp_timeout - connection timeout in ms, default Copy to clipboard10000

Copy to clipboardsmtp options

• Copy to clipboardsmtp_host - Postal SMTP host
• Copy to clipboardsmtp_port - SMTP port, default Copy to clipboard25
• Copy to clipboardsmtp_secure - Copy to clipboardtrue for TLS, default Copy to clipboardfalse
• Copy to clipboardsmtp_user - SMTP username
• Copy to clipboardsmtp_pass - SMTP password
• Copy to clipboardsmtp_timeout - connection timeout in ms, default Copy to clipboard10000

Usage

Add to Copy to clipboardapps/backend/medusa-config.ts under the notification module providers.

1234567891011121314151617181920
{
  resolve: "@medusajs/medusa/notification",
  options: {
    providers: [
      {
        resolve: "@uhlhosting/medusa-notification-postal",
        id: "postal",
        options: {
          channels: ["email"],
          auth_type: process.env.POSTAL_AUTH_TYPE || "smtp-api",
          from: process.env.POSTAL_FROM,

          // smtp-api
          base_url: process.env.POSTAL_BASE_URL,
          api_key: process.env.POSTAL_API_KEY,

          // smtp and smtp-ip
          smtp_host: process.env.POSTAL_SMTP_HOST,
          smtp_port: Number(process.env.POSTAL_SMTP_PORT || 25),
          smtp_secure: process.env.POSTAL_SMTP_SECURE === "true",

Workflow tracking

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

123456789101112131415
await notificationModuleService.createNotifications({
  channel: "email",
  to: "customer@example.com",
  template: "order-placed",
  provider_id: "postal",
  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.

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.

1234567891011121314151617181920
import { sendPostalEmailWorkflow } from "@uhlhosting/medusa-notification-postal"

const { result } = await sendPostalEmailWorkflow(req.scope).run({
  input: {
    to: "customer@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: "copy@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", ... } }