Notification postal

@uhlhosting/medusa-notification-postal

Postal notification provider for Medusa, combining SendGrid-style provider robustness with Resend-style option validation and template-friendly usage.

Release

• Current package version:
• License: MIT
• Changelog: CHANGELOG.md

Options

• auth_type - one of smtp-api, smtp-ip, smtp (default smtp-api)
• from - default sender e-mail address

smtp-api options

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

smtp-ip options

• smtp_host - Postal SMTP host
• smtp_port - SMTP port, default 25
• smtp_secure - true for TLS, default false
• smtp_timeout - connection timeout in ms, default 10000

smtp options

• smtp_host - Postal SMTP host
• smtp_port - SMTP port, default 25
• smtp_secure - true for TLS, default false
• smtp_user - SMTP username
• smtp_pass - SMTP password
• smtp_timeout - connection timeout in ms, default 10000

Usage

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

1{
2  resolve: "@medusajs/medusa/notification",
3  options: {
4    providers: [
5      {
6        resolve: "@uhlhosting/medusa-notification-postal",
7        id: "postal",
8        options: {
9          channels: ["email"],
10          auth_type: process.env.POSTAL_AUTH_TYPE || "smtp-api",
11          from: process.env.POSTAL_FROM,
12
13          // smtp-api
14          base_url: process.env.POSTAL_BASE_URL,
15          api_key: process.env.POSTAL_API_KEY,
16
17          // smtp and smtp-ip
18          smtp_host: process.env.POSTAL_SMTP_HOST,
19          smtp_port: Number(process.env.POSTAL_SMTP_PORT || 25),
20          smtp_secure: process.env.POSTAL_SMTP_SECURE === "true",
21          smtp_user: process.env.POSTAL_SMTP_USER,
22          smtp_pass: process.env.POSTAL_SMTP_PASS,
23        },
24      },
25    ],
26  },
27}

Workflow tracking

Use Medusa notification workflows and pass workflow metadata in provider_data:

1await notificationModuleService.createNotifications({
2  channel: "email",
3  to: "customer@example.com",
4  template: "order-placed",
5  provider_id: "postal",
6  content: {
7    subject: "Order confirmation",
8    html: "<p>Thanks for your order</p>",
9    text: "Thanks for your order",
10  },
11  provider_data: {
12    workflow_event: "order.placed",
13    workflow_run_id: "wf_run_123",
14  },
15})

The provider logs workflow_event and workflow_run_id for traceability in Medusa runtime logs.

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.

1import { sendPostalEmailWorkflow } from "@uhlhosting/medusa-notification-postal"
2
3const { result } = await sendPostalEmailWorkflow(req.scope).run({
4  input: {
5    to: "customer@example.com",
6    from: "custom-sender@example.com", // Optional, defaults to POSTAL_FROM
7    template: "custom-template-id",    // Optional
8    provider_data: {
9      subject: "Test Programmatic Email",
10      html: "<p>Hello, this is a test email sent programmatically.</p>",
11      text: "Hello, this is a test email sent programmatically.",
12      cc: "copy@example.com",
13      workflow_event: "admin.test_send",
14      workflow_run_id: "wf_run_manual_123"
15    }
16  }
17})
18
19// Result returns the delivery info:
20// { success: true, delivery: { message_id: "123", ... } }