Zeptomail

Name: Zeptomail
Author: Take3labs

ZeptoMail plugin for Medusa

Featured on Medusa

npm install @take3labs/zeptomail

@take3labs/zeptomail

A Zoho ZeptoMail notification provider plugin for Medusa v2.

This plugin allows your Medusa application to send transactional emails via ZeptoMail using template-based dispatch (). It provides an in-code template store/mapping mechanism to decouple Medusa application events from ZeptoMail template IDs.

Features

ZeptoMail Template Sending: Dispatches transactional emails via ZeptoMail's endpoint.
Decoupled Template Store: Map Medusa notification events (e.g. , ) directly to ZeptoMail or .
Flexible Credential Handling: Auto-normalizes authorization headers ( prefix) and regional endpoints (US, EU, IN, etc.).
Attachment & Merge Info Support: Automatically formats Medusa notification data and attachments for ZeptoMail.
Built for Medusa v2: Full support for Medusa v2 module providers and .

Prerequisites

A Zoho ZeptoMail account.
A configured Mail Agent with a verified sending domain.
A Send Mail Token generated in your Agent settings under SMTP / API.
Email Templates created in your Mail Agent with their respective Template Key (e.g. ) or Template Alias.

Installation

Install the plugin and its dependencies into your Medusa application:

npm install @take3labs/zeptomail

Environment Variables

Add the following environment variables to your Medusa project's file:

1# ZeptoMail API endpoint (optional, defaults to https://api.zeptomail.com/)
2# For EU: https://api.zeptomail.eu/
3# For IN: https://api.zeptomail.in/
4ZEPTOMAIL_URL=https://api.zeptomail.com/
5
6# Your ZeptoMail Send Mail Token (from Agent -> SMTP/API)
7# You can include or omit the "Zoho-enczapikey" prefix; the plugin normalizes it automatically.
8ZEPTOMAIL_TOKEN=Zoho-enczapikey phr09...
9
10# The verified sender email address in your ZeptoMail agent
11ZEPTOMAIL_FROM_ADDRESS=noreply@yourdomain.com
12
13# Optional sender display name
14ZEPTOMAIL_FROM_NAME="My Store"

Configuration

1import { defineConfig, Modules } from "@medusajs/framework/utils"
2
3export default defineConfig({
// ...
modules: [
  {
    resolve: "@medusajs/medusa/notification",
    options: {
      providers: [
        {
          resolve: "@take3labs/zeptomail/providers/zeptomail",
          id: "zeptomail",
          options: {
            channels: ["email"],
            url: process.env.ZEPTOMAIL_URL,
            token: process.env.ZEPTOMAIL_TOKEN,
            from_address: process.env.ZEPTOMAIL_FROM_ADDRESS,
            from_name: process.env.ZEPTOMAIL_FROM_NAME,
            templateMap: {
              "admin-password-reset": "2d6f.ca206d0a61dd719.k1.0a844e61-8e56-11f0-8679-5254001dc20d.199341ee643",
              "customer-password-reset": "your_customer_pwd_reset_alias",
              "order-placed": "order_confirmation_template_alias",
              "invite-created": "2d6f.ca206d0a61dd719.k1.invite_template_id",
            },
          },
        },
      ],
    },
  },
],
31})

Template Store & Decoupling

The option allows you to map Medusa internal notification templates to ZeptoMail templates.

You can configure values as:

A Template Key (ZeptoMail's unique identifier):

"admin-password-reset": "2d6f.ca206d0a61dd719.k1.0a844e61-8e56-11f0-8679-5254001dc20d.199341ee643"

A Template Alias (Custom human-readable alias configured in ZeptoMail):
```
"order-placed": "order_placed_alias"
```

An Explicit Object:

1"customer-welcome": {
2  template_alias: "welcome_email",
3},
4"invoice-receipt": {
5  template_key: "2d6f.ca206d0a61dd719.k1.receipt_key",
6}

Predefined Constants

You can also import common Medusa notification template event names from :

1import { MedusaNotificationTemplates } from "@take3labs/zeptomail"
2
3// MedusaNotificationTemplates.ADMIN_PASSWORD_RESET -> "admin-password-reset"
4// MedusaNotificationTemplates.CUSTOMER_PASSWORD_RESET -> "customer-password-reset"
5// MedusaNotificationTemplates.ORDER_PLACED -> "order-placed"
6// MedusaNotificationTemplates.ORDER_CANCELED -> "order-canceled"
7// MedusaNotificationTemplates.ORDER_SHIPPED -> "order-shipped"
8// MedusaNotificationTemplates.INVITE_CREATED -> "invite-created"

Triggering Notifications

When sending notifications via Medusa's notification service or workflow step:

1import { useNotificationService } from "@medusajs/medusa"
2
3await notificationModuleService.createNotifications({
4  to: "customer@example.com",
5  channel: "email",
6  template: "admin-password-reset", // matches the key in your templateMap
7  data: {
8    user_name: "John Doe",
9    reset_url: "https://admin.yourstore.com/reset-password?token=xyz",
10  },
11})