Ecomail

Name: Ecomail
Author: Davidhotar

Ecomail integration plugin for Medusa v2 - email marketing and transaction tracking

Featured on Medusa

npm install medusa-plugin-ecomail

medusa-plugin-ecomail

Ecomail integration plugin for Medusa v2 - email marketing and transaction tracking.

Features

📧 Subscriber Management - Add, update, and manage Ecomail subscribers
🛒 E-commerce Tracking - Automatically track order transactions in Ecomail
🎯 Smart Subscription - Intelligent handling of new subscribers, updates, and resubscriptions
🎨 Admin UI - Built-in admin panel for testing and managing subscribers
🔄 Auto-sync - Automatic synchronization of customer data with Ecomail lists

Compatibility

This plugin is compatible with Medusa v2 (>= 2.11.2).

Installation

1npm install medusa-plugin-ecomail
2# or
3yarn add medusa-plugin-ecomail

Configuration

Basic Configuration (Default Mode)

Add the plugin to your :

1import { defineConfig } from '@medusajs/framework/utils'
2
3export default defineConfig({
plugins: [
  {
    resolve: 'medusa-plugin-ecomail',
    options: {
      ecomailListId: process.env.ECOMAIL_LIST_ID,
      ecomailToken: process.env.ECOMAIL_TOKEN,
      shopDomain: process.env.SHOP_DOMAIN, // optional
    },
  },
],
14})

Default Behavior: All customers are automatically synced to Ecomail when they place an order.

For GDPR compliance, enable explicit consent requirement:

1import { defineConfig } from '@medusajs/framework/utils'
2
3export default defineConfig({
plugins: [
  {
    resolve: 'medusa-plugin-ecomail',
    options: {
      ecomailListId: process.env.ECOMAIL_LIST_ID,
      ecomailToken: process.env.ECOMAIL_TOKEN,
      shopDomain: process.env.SHOP_DOMAIN, // optional
      requireExplicitConsent: true, // Only sync with explicit consent
      consentMetadataKey: 'ecomail_consent', // optional, this is the default
    },
  },
],
16})

GDPR Behavior: Only customers who explicitly consent are synced to Ecomail.

Environment Variables

Add these to your file:

1ECOMAIL_LIST_ID=your_list_id
2ECOMAIL_TOKEN=your_api_token
3SHOP_DOMAIN=your-shop.com # optional

Configuration Options

Type	Required	Default	Description
string	Yes	-	Your Ecomail list ID
string	Yes	-	Your Ecomail API token
string	No		Your shop domain for transaction tracking
boolean	No		Require explicit consent before syncing customers
string	No		Metadata key to check for consent

Automatic Syncing

The plugin automatically syncs customers to Ecomail when orders are placed. No additional code is required!

How It Works

Customer places an order → event fires
Plugin checks consent (if is enabled)
Syncs customer data to Ecomail list
Tracks transaction for e-commerce analytics

Default Mode ()

All customers are automatically synced to Ecomail when they place an order. No consent checking is performed.

Only customers who explicitly consent are synced. The plugin checks for consent in order or customer metadata.

How to pass consent from your storefront:

When completing checkout, include the consent flag in the order metadata:

1// Example: Next.js/React storefront
2const completeCheckout = async () => {
3  await sdk.store.cart.complete(cartId, {
4    metadata: {
5      ecomail_consent: userAcceptedNewsletter, // true or false
6    },
7  })
8}

1// Example: In a custom checkout flow
2await fetch('/store/checkout/complete', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
  cart_id: cartId,
  metadata: {
    ecomail_consent: true, // User checked the newsletter box
  },
}),
11})

The plugin checks for consent in this order:

Order metadata ()
Customer metadata ()

If consent is , the customer is synced. If or missing (in GDPR mode), the sync is skipped.

You can use a different metadata key for consent:

1{
resolve: 'medusa-plugin-ecomail',
options: {
  // ... other options
  requireExplicitConsent: true,
  consentMetadataKey: 'marketing_consent', // Use your own key
}
8}

Then pass it from your storefront:

1metadata: {
2  marketing_consent: true
3}

Usage

In Your Code

Import and use the Ecomail service in your custom modules, subscribers, or workflows:

1import { ECOMAIL_MODULE } from 'medusa-plugin-ecomail'
2import type EcomailService from 'medusa-plugin-ecomail'
3
4// In a subscriber or workflow
5const ecomailService = container.resolve<EcomailService>(ECOMAIL_MODULE)
6
7// Add a subscriber
8await ecomailService.addSubscriber({
9  email: 'customer@example.com',
10  name: 'John',
11  surname: 'Doe',
12  city: 'Prague',
13  country: 'CZ',
14})
15
16// Smart add/update (checks if exists, handles resubscriptions)
17await ecomailService.addSubscriberToListIfNotAdded({
18  email: 'customer@example.com',
19  name: 'John',
20  surname: 'Doe',
21})
22
23// Track an order transaction
24await ecomailService.addTransaction(order, customer)

Admin Panel

The plugin adds an Ecomail settings page to your Medusa admin panel where you can:

Test subscriber operations (Check, Add, Update, Smart Add)
View subscriber details
Verify plugin configuration

Access it at: Settings → Ecomail

API Reference

EcomailService Methods

Adds a new subscriber to the Ecomail list.

Parameters:

(required) - Subscriber email
- First name
- Last name
- City
- Country code
- Postal code
- Company name
- Street address
- Phone number

Retrieves an existing subscriber from the list.

Updates an existing subscriber's data.

Smart method that:

Adds subscriber if they don't exist
Updates subscriber if they exist and are subscribed
Resubscribes if they exist but are unsubscribed

Tracks an e-commerce transaction in Ecomail with order details and items.

Custom Integration Examples

Using the Service Directly

While the plugin automatically syncs on order placement, you can also use the service directly for custom scenarios:

1// Example: Add subscriber on customer registration
2import { SubscriberArgs } from '@medusajs/framework'
3import { ECOMAIL_MODULE } from 'medusa-plugin-ecomail'
4import type EcomailService from 'medusa-plugin-ecomail'
5
6export default async function customerCreatedHandler({
7  event: { data },
8  container,
9}: SubscriberArgs<{ id: string }>) {
10  const ecomailService = container.resolve<EcomailService>(ECOMAIL_MODULE)
11  const customerService = container.resolve('customerService')
12  
13  const customer = await customerService.retrieve(data.id)
14
15  await ecomailService.addSubscriberToListIfNotAdded({
16    email: customer.email,
17    name: customer.first_name,
18    surname: customer.last_name,
19  })
20}
21
22export const config = {
23  event: 'customer.created',
24}

Manual Sync from API Route

1// Example: Custom API route for newsletter subscription
2import { MedusaRequest, MedusaResponse } from '@medusajs/framework'
3import { ECOMAIL_MODULE } from 'medusa-plugin-ecomail'
4import type EcomailService from 'medusa-plugin-ecomail'
5
6export async function POST(req: MedusaRequest, res: MedusaResponse) {
7  const ecomailService = req.scope.resolve<EcomailService>(ECOMAIL_MODULE)
8  const { email, name, surname } = req.body
9
10  await ecomailService.addSubscriberToListIfNotAdded({
11    email,
12    name,
13    surname,
14  })
15
16  res.json({ success: true })
17}

TypeScript Types

1type EcomailModuleOptions = {
ecomailListId: string
ecomailToken: string
shopDomain?: string
requireExplicitConsent?: boolean
consentMetadataKey?: string
7}
8
9type SubscriberDataT = {
email: string
name?: string
surname?: string
city?: string
country?: string
zip?: string
company?: string
street?: string
phone?: string
[key: string]: string | undefined
20}

Testing

Default Mode (sync everyone):

Configure plugin without or set it to
Place a test order
Verify customer appears in Ecomail list
Verify transaction is tracked

GDPR Mode (require consent):

Configure plugin with
Place order WITH consent ()
- Customer should be synced ✓
Place order WITHOUT consent ()
- Customer should NOT be synced ✓
Place order with NO metadata
- Customer should NOT be synced ✓

Testing via Admin Panel

The plugin includes an admin panel (Settings → Ecomail) where you can:

Test adding subscribers manually
Check if a subscriber exists
Update subscriber information
Verify your Ecomail connection

Error Handling

The plugin is designed to be resilient:

Ecomail sync failures do not break the order flow
All errors are logged for debugging
Orders complete successfully even if Ecomail is unavailable

Development

1# Build the plugin
2yarn build
3
4# Development mode with watch
5yarn dev

Resources

License

MIT

Author

Gramino

Made with ❤️ for the Medusa community

Ecomail

medusa-plugin-ecomail

Features

Compatibility

Installation

Configuration

Basic Configuration (Default Mode)

Environment Variables

Configuration Options

Automatic Syncing

How It Works

Default Mode ()

Usage

In Your Code

Admin Panel

API Reference

EcomailService Methods

Custom Integration Examples

Using the Service Directly

Manual Sync from API Route

TypeScript Types

Testing

Testing via Admin Panel

Error Handling

Development

Resources

License

Author

More in this category

Nodemailer

Mailgun

Postmark

Ecomail

medusa-plugin-ecomail

Features

Compatibility

Installation

Configuration

Basic Configuration (Default Mode)

GDPR-Compliant Configuration

Environment Variables

Configuration Options

Automatic Syncing

How It Works

Consent Handling

Default Mode (requireExplicitConsent: false)

GDPR Mode (requireExplicitConsent: true)

Customizing the Consent Key

Usage

In Your Code

Admin Panel

API Reference

EcomailService Methods

addSubscriber(data: SubscriberDataT)

getExistingSubscriber(email: string)

updateSubscriber(data: SubscriberDataT)

addSubscriberToListIfNotAdded(data: SubscriberDataT)

addTransaction(order: OrderDTO, customer: CustomerDTO)

Custom Integration Examples

Using the Service Directly

Manual Sync from API Route

TypeScript Types

Testing

Testing Consent Modes

Testing via Admin Panel

Error Handling

Development

Resources

License

Author

More in this category

Nodemailer

Mailgun

Postmark

Default Mode ()

GDPR Mode ()