Install

npm install medusa-notification-groundmail

GROUNDMAIL_API_KEY=gm_your_key_here

Configure

// medusa-config.ts
module.exports = defineConfig({
  // ...
  modules: [
    {
      resolve: '@medusajs/medusa/notification',
      options: {
        providers: [
          {
            resolve: 'medusa-notification-groundmail',
            id: 'groundmail',
            options: {
              channels: ['email'],
              api_key: process.env.GROUNDMAIL_API_KEY,
              from: 'Acme <[email protected]>',
            },
          },
        ],
      },
    },
  ],
})

Send

From a subscriber or workflow:

await notificationModuleService.createNotifications({
  to: order.email,
  channel: 'email',
  template: 'order-placed',
  data: { order: { display_id: order.display_id, total: order.total } },
})

Without content, the provider sends the Groundmail template whose id or alias matches template, with data as its variables. Nested keys are joined with underscores, so {{order_display_id}} in the template reads data.order.display_id.

To send your own markup instead, pass content: { subject, html, text }.

Options

| Option | Purpose | |--------|---------| | api_key | Groundmail API key. Falls back to GROUNDMAIL_API_KEY | | from | Default From address, on a verified domain | | reply_to | Default Reply-To address | | templates | Map Medusa template names to Groundmail templates, e.g. { "order-placed": "order_confirmation" } | | base_url | Override the API base URL |

provider_data on a notification can carry cc, bcc, replyTo, tags, headers, idempotencyKey and scheduledAt.

Contributing

Found a bug or want something added? Open an issue. This code is published here on each release, so we port fixes rather than merging pull requests directly. The HTTP client itself is the groundmail package.

Why Groundmail

• Our own mail servers and IP space. Your password resets and receipts don't share a pool with bulk marketing senders.
• Transactional email only. No newsletters or cold outreach on the platform, which keeps the sending reputation clean.
• Start free. 3,000 emails a month on the Free plan; Pro is 50,000 emails for $20/month. Dedicated IPs on Scale.
• Built for code and for agents. REST API, SMTP, SDKs for Node, Python, Go, PHP and Ruby, a CLI, and an MCP server for Claude, ChatGPT and Cursor.

All Groundmail libraries

| Use | Package | |-----|---------| | Node.js / TypeScript | groundmail on npm | | Python (Django), Go, Ruby (Rails Action Mailer) | Groundmail/groundmail-sdks | | PHP | Groundmail/groundmail-php | | Laravel | Groundmail/groundmail-laravel | | Symfony Mailer | Groundmail/groundmail-symfony-mailer | | Nodemailer | Groundmail/groundmail-nodemailer | | NestJS | Groundmail/nestjs-groundmail | | Strapi | Groundmail/strapi-provider-email-groundmail | | Medusa | Groundmail/medusa-notification-groundmail | | AdonisJS | Groundmail/adonisjs-groundmail | | Phoenix (Swoosh) | Groundmail/swoosh_groundmail | | CLI | groundmail-cli on npm | | MCP server (Claude, ChatGPT, Cursor) | Groundmail/groundmail-mcp | | Agent skills and Claude Code plugin | Groundmail/groundmail-skills | | Email templates (React Email, MJML, HTML) | Groundmail/email-templates |

Website · Docs · Pricing · Sign up free