medusa-plugin-postmark

stars - medusa-plugin-postmark forks - medusa-plugin-postmark

GitHub tag License issues - medusa-plugin-postmark

Notifications plugin for Medusa ecommerce server that sends transactional emails via PostMark.

Features

  • Uses the email templating features built into Postmark
  • You can import/use tools like stripo.email
  • The plugin is in active development. If you have any feature requests, please open an issue.
  • Create PDF invoices and credit notes and attach them to the email
  • Send out upsell emails to customers that have recently placed an order with certain collections
  • Send out automated abandoned cart emails to customers that have abandoned their cart (based on last updated date of cart)

Configuration

The plugin requires several configuration options and environment variables to function correctly.

Environment Variables

  • POSTMARK_API_KEY: Your Postmark server token
  • POSTMARK_FROM: Default sender email address
  • POSTMARK_BCC: Default bcc email address

Setup

  1. Install the plugin and its dependencies.
  2. Add the plugin to your Medusa configuration.
  3. Set the required environment variables.
  4. Configure reminder schedules and templates as needed.

Example: Plugin Registration

Add the plugin to your medusa-config.ts:

defineConfig({
	// ...
	plugins: [
    // ...
		{
			resolve: "medusa-plugin-postmark",
			options: {
				apiKey: process.env.POSTMARK_API_KEY!,
			}
		},
	]
})

Example: Adding the Postmark Notification Provider

To use Postmark as a notification provider, add it to the modules property in your Medusa config:

defineConfig({
	// ...
	modules: [
		{
			resolve: "@medusajs/medusa/notification",
			options: {
				providers: [
					{
						resolve: "medusa-plugin-postmark/providers/postmark",
						id: "postmark",
						options: {
							channels: ["email"],
							apiKey: process.env.POSTMARK_API_KEY!,
              default: {
                  from: process.env.POSTMARK_FROM,
                  bcc: process.env.POSTMARK_BCC,
              }
						},
					},
				],
			},
		},
	],
})

Only one provider can be set per channel (e.g., "email").

Options

  • Reminder Schedules: Configure delays, template associations, and flags.
  • Templates: Manage templates and layouts through the admin interface or API.

Refer to the other documentation sections for details on each configuration area.

Events

The plugin uses event-driven workflows to automate abandoned cart notifications and template validation. Events are triggered by cart updates, schedule changes, and workflow executions.

Main Events

  • Cart Abandoned: Triggers the abandoned cart workflow to check for eligible reminders.
  • Reminder Schedule Updated: Re-evaluates which carts are eligible for notifications.
  • Template Validated: Ensures all required variables are present before sending.

Workflows

Abandoned Cart Workflow

  • Fetches eligible carts based on reminder schedules.
  • Determines which reminders should be sent and when.
  • Triggers notification sending using the associated Postmark template.

Notification Data Workflow

  • Prepares the data required for each notification, including template variables.
  • Validates that all required variables are present for the selected template.

These workflows ensure that notifications are sent reliably and only when all conditions are met.

Templates

Templates are managed through the Postmark integration and are used to render the content of abandoned cart and other notification emails. The plugin provides CRUD operations for templates and supports validation to ensure all required variables are provided.

Features

  • List Templates: Fetch all templates from Postmark.
  • Create Template: Add a new template to Postmark.
  • Update Template: Modify an existing template.
  • Delete Template: Remove a template from Postmark.
  • Layout Templates: Support for layout templates in Postmark.
  • Validation: Check that all required variables are present in the template model before sending.

Template Association

Each reminder schedule is linked to a specific template by template_id. Templates can be standard or layout types, and are validated before use in workflows.

Variables

Template variables are the dynamic data passed to Postmark templates when sending notifications. The plugin ensures that all required variables are generated and validated before sending.

Generation

  • Variables are generated by the notification data workflow based on the cart, customer, and reminder schedule context.
  • Each template may require different variables, which are validated before sending.

Validation

  • The plugin uses Postmark's template validation endpoint to check for missing variables.
  • If required variables are missing, the notification is not sent and an error is logged.

Usage

  • Variables are passed as the TemplateModel when sending templated emails through Postmark.
  • Ensure your templates reference only variables that are provided by the workflow.

Reminder Schedules

Reminder schedules define when and how abandoned cart reminder emails are sent to customers. Each schedule specifies a set of delays (in ISO 8601 duration format), the Postmark template to use, and additional flags to control notification behavior.

Fields

  • id: Unique identifier for the schedule.
  • enabled: Whether the schedule is active.
  • template_id: The Postmark template associated with this schedule.
  • delays_iso: Array of ISO 8601 durations (e.g., ['PT1H', 'P1D']) specifying when reminders are sent after cart abandonment.
  • notify_existing: If true, carts created before a schedule update are eligible for notifications.
  • reset_on_cart_update: If true, the notification cycle restarts if the cart is updated after abandonment.
  • created_at / updated_at / deleted_at: Timestamps for schedule lifecycle management.

Behavior

  • Each schedule can be enabled or disabled.
  • Multiple schedules can exist, each with its own template and delays.
  • The system ensures that reminders are not sent more than once for the same delay and cart, unless reset_on_cart_update is enabled and the cart is updated.
  • Schedules are linked to templates, and referential integrity is enforced.

Use Case

Reminder schedules are used by the abandoned cart workflow to determine which customers should receive reminder emails and when, ensuring a flexible and robust notification strategy.

API Routes

The plugin exposes several API endpoints for managing reminder schedules, templates, layouts, and sending emails through Postmark. All routes are proxied through the Medusa server for security and consistency.

Reminder Schedules

  • GET /admin/postmark/abandoned-carts/reminders/schedules — List all reminder schedules
  • GET /admin/postmark/abandoned-carts/reminders/schedules/:id — Get a reminder schedule by id
  • POST /admin/postmark/abandoned-carts/reminders/schedules — Create a new reminder schedule
  • POST /admin/postmark/abandoned-carts/reminders/schedules/:id — Update a reminder schedule
  • DELETE /admin/postmark/abandoned-carts/reminders/schedules/:id — Delete a reminder schedule

Templates

  • GET /admin/postmark/templates — List all templates
  • GET /admin/postmark/templates/:id — Get a template by ID
  • POST /admin/postmark/templates — Create a new template
  • POST /admin/postmark/templates/:id — Update a template
  • DELETE /admin/postmark/templates/:id — Delete a template

Options

  • GET /admin/postmark/options — Returns configuration options about the postmark server, currently just returns the server's ID.

Validation

  • POST /admin/postmark/abandoned-carts/reminders/validate — Validate reminder schedules against template data,to make sure that no template misses any data.