E-commerce Integrations

Wire InboxOS into your store in minutes. Every order trigger, abandoned cart, and customer lifecycle event — sent reliably via SES on Cloudflare's edge.

Each integration ships as a thin adapter that receives a platform webhook or hook call, maps the event payload to a Mailgrid POST /api/emails request, and fires it. All adapters share the same two required environment variables:

Shopify

The Shopify integration is a Shopify CLI app (Node.js) deployed as a Cloudflare Worker that registers GDPR-compliant webhooks for order and cart events and forwards them to Mailgrid. It handles Shopify HMAC verification before touching any payload.

Setup

1. Clone the adapter skeleton into your project:
   terminal

   git clone https://github.com/mailgrid/integrations integrations
   cd integrations/shopify

2. Install dependencies and authenticate with the Shopify CLI:
   terminal

   npm install
   shopify app login --store your-store.myshopify.com

3. Copy .env.example to .env and fill in your credentials (see env vars table below).
4. Register the webhooks against your store:
   register-webhooks.mjs

   import { registerWebhook } from './src/shopify/webhooks.mjs';
   
   const topics = [
     'orders/create',
     'orders/fulfilled',
     'orders/cancelled',
     'checkouts/create',   // abandoned cart seed
     'checkouts/update',
     'customers/create',
     'refunds/create',
   ];
   
   for (const topic of topics) {
     await registerWebhook({
       topic,
       address: `${process.env.WORKER_URL}/webhooks/shopify`,
       format:  'json',
     });
     console.log(`registered: ${topic}`);
   }

5. Deploy the Worker:
   terminal

   npx wrangler deploy

Key configuration

import { verifyHmac, mapOrder } from './utils.mjs';

export async function handleShopify(request, env) {
  const hmac  = request.headers.get('X-Shopify-Hmac-Sha256');
  const topic = request.headers.get('X-Shopify-Topic');
  const body  = await request.text();

  if (!await verifyHmac(body, hmac, env.SHOPIFY_WEBHOOK_SECRET)) {
    return new Response('Forbidden', { status: 401 });
  }

  const payload = JSON.parse(body);

  if (topic === 'orders/create') {
    await fetch('https://api.mailgrid.space/api/emails', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${env.MAILGRID_KEY}`,
        'Content-Type':  'application/json',
      },
      body: JSON.stringify(mapOrder(payload, env.MAILGRID_FROM, env.ORDER_TEMPLATE_ID)),
    });
  }

  return new Response('ok');
}

Environment variables

Supported events

• orders/create — order confirmation email
• orders/fulfilled — shipping notification with tracking number
• orders/cancelled — cancellation notice
• checkouts/create + checkouts/update — abandoned cart sequence (delayed send)
• customers/create — welcome email
• refunds/create — refund receipt

WooCommerce

The WooCommerce integration is a drop-in PHP plugin that hooks into woocommerce_order_status_changed and related actions to dispatch transactional emails via Mailgrid instead of WooCommerce's built-in mailer. It overrides WC_Email at the transport layer so all existing email templates continue to work.

Setup

1. Copy the plugin folder into your WordPress installation:
   terminal

   cp -r integrations/woocommerce wp-content/plugins/mailgrid-woocommerce
   cd wp-content/plugins/mailgrid-woocommerce && composer install

2. Activate the plugin in WP Admin → Plugins.
3. Navigate to WooCommerce → Settings → Mailgrid and enter your API key and from-address.
4. Optionally map each WooCommerce email class to a Mailgrid template ID in the settings table.

Key configuration

class Mailgrid_Transport {

    public function __construct() {
        add_action( 'woocommerce_order_status_changed',
            [ $this, 'on_order_status_changed' ], 10, 4 );
        add_action( 'woocommerce_checkout_order_created',
            [ $this, 'on_order_created' ] );
    }

    public function on_order_status_changed( int $order_id, string $from,
                                               string $to, WC_Order $order ) {
        if ( $to === 'processing' ) {
            $this->send_via_mailgrid( $order, 'order_confirmation' );
        } elseif ( $to === 'completed' ) {
            $this->send_via_mailgrid( $order, 'order_fulfilled' );
        } elseif ( $to === 'cancelled' ) {
            $this->send_via_mailgrid( $order, 'order_cancelled' );
        }
    }

    private function send_via_mailgrid( WC_Order $order, string $event ) {
        wp_remote_post( 'https://api.mailgrid.space/api/emails', [
            'headers' => [
                'Authorization' => 'Bearer ' . get_option( 'mailgrid_api_key' ),
                'Content-Type'  => 'application/json',
            ],
            'body' => wp_json_encode( $this->build_payload( $order, $event ) ),
        ] );
    }
}

Environment variables

Supported events

• woocommerce_order_status_changed → processing — order confirmation
• woocommerce_order_status_changed → completed — order fulfilled / shipped
• woocommerce_order_status_changed → cancelled — order cancellation
• woocommerce_order_status_changed → refunded — refund notice
• woocommerce_checkout_order_created — post-checkout welcome sequence seed
• woocommerce_created_customer — new customer welcome email
• wc-abandoned-cart — via companion wc-cart-abandonment-recovery bridge (optional)

OpenCart

The OpenCart integration is a PHP extension that registers listeners in OpenCart's event system (3.x / 4.x). It intercepts model/checkout/order/addOrder/after and related events, then calls Mailgrid instead of the platform's default mail() wrapper.

Setup

1. Upload the extension via Admin → Extensions → Installer and select mailgrid.ocmod.zip from integrations/opencart/.
2. Navigate to Extensions → Extensions → Modules, find Mailgrid, and click Install, then Edit.
3. Enter your API key, from-address, and optional template IDs, then click Save.
4. Refresh the OpenCart modification cache: Admin → Extensions → Modifications → Refresh.

Key configuration

class MailgridClient {

    private string $api_key;
    private string $from;

    public function __construct(string $api_key, string $from) {
        $this->api_key = $api_key;
        $this->from    = $from;
    }

    public function send(array $payload): void {
        $ch = curl_init('https://api.mailgrid.space/api/emails');
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST           => true,
            CURLOPT_POSTFIELDS     => json_encode($payload),
            CURLOPT_HTTPHEADER     => [
                'Authorization: Bearer ' . $this->api_key,
                'Content-Type: application/json',
            ],
        ]);
        curl_exec($ch);
        curl_close($ch);
    }
}

// Event listener registered in extension controller:
// $this->event->register(
//   'model/checkout/order/addOrder/after',
//   new Action('extension/module/mailgrid/onOrderCreate'));

Environment variables

Supported events

• model/checkout/order/addOrder/after — order placed confirmation
• model/checkout/order/addOrderHistory/after — status change (shipped, cancelled, refunded)
• model/account/customer/addCustomer/after — new customer welcome
• model/account/customer/editPassword/after — password changed notice
• catalog/model/account/customer/resetPassword/after — password reset email

Magento 2

The Magento 2 integration is a Composer package that registers a sales_order_place_after observer. It replaces Magento's Magento_Email transport for all transactional mail while keeping the existing template system intact. Compatible with Magento Open Source 2.4.x and Adobe Commerce.

Setup

1. Require the package:
   terminal

   composer require mailgrid/magento2-transport
   php bin/magento module:enable Mailgrid_Transport
   php bin/magento setup:upgrade
   php bin/magento cache:flush

2. Set the API key and from-address via the Magento CLI:
   terminal

   php bin/magento config:set mailgrid/transport/api_key "mb_live_…"
   php bin/magento config:set mailgrid/transport/from_address "orders@yourdomain.com"
   php bin/magento config:set mailgrid/transport/enabled 1
   php bin/magento cache:flush

3. Verify by placing a test order or using Stores → Configuration → Advanced → System → Mail Sending Settings → Test.

Key configuration

namespace Mailgrid\Transport\Observer;

use Magento\Framework\Event\ObserverInterface;
use Magento\Framework\Event\Observer;
use Mailgrid\Transport\Model\ApiClient;

class OrderPlaceAfter implements ObserverInterface {

    public function __construct(
        private readonly ApiClient $client
    ) {}

    public function execute(Observer $observer): void {
        $order = $observer->getEvent()->getOrder();
        if (!$order || !$order->getCustomerEmail()) {
            return;
        }
        $this->client->send([
            'to'         => $order->getCustomerEmail(),
            'subject'    => 'Order #' . $order->getIncrementId() . ' confirmed',
            'templateId' => $this->client->templateFor('order_confirmation'),
            'variables'  => [
                'orderId'   => $order->getIncrementId(),
                'firstName' => $order->getCustomerFirstname(),
                'total'     => $order->getGrandTotal(),
            ],
        ]);
    }
}

Environment variables

Supported events

• sales_order_place_after — order confirmation
• sales_order_shipment_save_after — shipment / tracking update
• sales_order_creditmemo_save_after — refund confirmation
• customer_register_success — new account welcome
• customer_forgot_password — password reset
• sales_order_invoice_save_after — invoice email

PrestaShop

The PrestaShop integration is a native module that hooks into actionValidateOrder and the sendMail override to intercept all outbound mail. Compatible with PrestaShop 1.7.x and 8.x.

Setup

1. Upload the module:
   terminal

   cp -r integrations/prestashop/mailgridtransport modules/
   cd modules/mailgridtransport && composer install --no-dev

2. In Modules → Module Manager, search for Mailgrid Transport and click Install.
3. Click Configure and enter your API key, from-address, and optional template IDs.
4. Enable the Override sendMail toggle to intercept all PrestaShop system mail (recommended).

Key configuration

class MailgridTransport extends Module {

    public function install(): bool {
        return parent::install()
            && $this->registerHook('actionValidateOrder')
            && $this->registerHook('actionOrderStatusUpdate')
            && $this->registerHook('actionCustomerAccountAdd');
    }

    public function hookActionValidateOrder(array $params): void {
        $order    = $params['order'];
        $customer = new Customer((int) $order->id_customer);

        $this->mailgridSend([
            'to'         => $customer->email,
            'subject'    => $this->l('Order confirmed') . ' #' . $order->reference,
            'templateId' => Configuration::get('MAILGRID_ORDER_TEMPLATE'),
            'variables'  => [
                'reference' => $order->reference,
                'firstName' => $customer->firstname,
                'total'     => $order->getOrdersTotalPaid(),
            ],
        ]);
    }
}

Environment variables

Supported events

• actionValidateOrder — order placed confirmation
• actionOrderStatusUpdate — status transitions (shipped, delivered, cancelled)
• actionCustomerAccountAdd — new account welcome
• actionGetExtraMailTemplateVars — pass store variables into templates
• Mail::send() override — catches all remaining PrestaShop system mail when override is enabled

BigCommerce

BigCommerce does not expose server-side hooks, so the integration uses a Cloudflare Worker as a webhook receiver. The Worker registers BigCommerce webhooks via the Store Management API on first deploy and then relays events to Mailgrid. A register-webhooks.mjs script handles the registration step.

Setup

1. Enter the integrations/bigcommerce/ directory and install dependencies:
   terminal

   cd integrations/bigcommerce
   npm install

2. Copy .env.example to .env and fill in your BigCommerce API credentials and Mailgrid key.
3. Register webhooks with the BigCommerce API:
   register-webhooks.mjs

   import { register } from './src/register.mjs';
   
   const scopes = [
     'store/order/created',
     'store/order/statusUpdated',
     'store/order/refund/created',
     'store/cart/abandoned',
     'store/customer/created',
     'store/shipment/created',
   ];
   
   for (const scope of scopes) {
     const result = await register({
       scope,
       destination: `${process.env.WORKER_URL}/webhooks/bigcommerce`,
       is_active: true,
     });
     console.log(`[${result.id}] ${scope}`);
   }

4. Deploy the Worker:
   terminal

   npx wrangler deploy

Key configuration

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    if (url.pathname !== '/webhooks/bigcommerce') {
      return new Response('Not found', { status: 404 });
    }

    const { scope, data } = await request.json();

    if (scope === 'store/order/created') {
      const order = await fetchOrder(data.id, env);
      await sendOrderConfirmation(order, env);
    } else if (scope === 'store/cart/abandoned') {
      await env.ABANDONED.put(data.cartId,
        JSON.stringify(data),
        { expirationTtl: 86400 });
      // KV-backed delay: a second cron Worker reads and fires
    }

    return new Response('ok');
  }
};

Environment variables

Supported events

• store/order/created — order confirmation
• store/order/statusUpdated — status change notification
• store/shipment/created — shipping notification
• store/order/refund/created — refund receipt
• store/cart/abandoned — abandoned cart (KV-delayed)
• store/customer/created — welcome email

Medusa.js

The Medusa.js integration is a notification subscriber that listens for Medusa events via the event bus and dispatches them to Mailgrid. It ships as a drop-in src/subscribers/mailgrid.ts file compatible with Medusa v1.x and v2 (the v2 module variant is in integrations/medusa/v2/).

Setup

1. Copy the subscriber into your Medusa project:
   terminal

   cp integrations/medusa/src/subscribers/mailgrid.ts src/subscribers/
   cp integrations/medusa/src/services/mailgrid-client.ts src/services/

2. Add the required env vars to your .env (see table below).
3. Restart the Medusa server — subscribers are auto-discovered on startup.

Key configuration

import { SubscriberArgs, SubscriberConfig } from '@medusajs/medusa';
import MailgridClient from '../services/mailgrid-client';

export default async function mailgridOrderSubscriber({
  data, eventName, container,
}: SubscriberArgs<{ id: string }>) {
  const orderService = container.resolve('orderService');
  const order = await orderService.retrieve(data.id, {
    relations: ['customer', 'items', 'shipping_address'],
  });

  const client = new MailgridClient(process.env.MAILGRID_KEY!);

  await client.send({
    from:        process.env.MAILGRID_FROM!,
    to:          order.email,
    templateId:  process.env.MAILGRID_ORDER_TEMPLATE,
    variables: {
      orderId:    order.display_id,
      firstName:  order.customer?.first_name,
      total:      order.total / 100,
      currency:   order.currency_code.toUpperCase(),
    },
  });
}

export const config: SubscriberConfig = {
  event: [
    'order.placed',
    'order.shipment_created',
    'order.canceled',
    'order.refund_created',
    'customer.created',
  ],
};

Environment variables

Supported events

• order.placed — order confirmation
• order.shipment_created — shipping notification
• order.canceled — cancellation notice
• order.refund_created — refund receipt
• order.return_requested — return initiation email
• customer.created — welcome email
• customer.password_reset — password reset link
• invite.created — staff invitation email

Swell

The Swell integration is a lightweight Cloudflare Worker that receives Swell webhooks, verifies the HMAC signature, and forwards order and customer events to Mailgrid. Swell fires webhooks for all lifecycle events over HTTPS; the Worker handles deduplication via Mailgrid's idempotency key.

Setup

1. Deploy the Worker from integrations/swell/:
   terminal

   cd integrations/swell
   npm install
   npx wrangler secret put MAILGRID_KEY
   npx wrangler secret put SWELL_SECRET_KEY
   npx wrangler deploy

2. In the Swell dashboard, go to Developer → Webhooks → Add endpoint and point it at https://your-worker.workers.dev/webhooks/swell.
3. Select the events you want to receive (see list below) and save.

Key configuration

import { verifySwellHmac, mapSwellEvent } from './utils.mjs';

export default {
  async fetch(request, env) {
    const sig  = request.headers.get('x-swell-signature');
    const body = await request.text();

    if (!await verifySwellHmac(body, sig, env.SWELL_SECRET_KEY)) {
      return new Response('Forbidden', { status: 401 });
    }

    const event   = JSON.parse(body);
    const payload = mapSwellEvent(event, env.MAILGRID_FROM);

    if (!payload) return new Response('ok'); // unhandled type

    await fetch('https://api.mailgrid.space/api/emails', {
      method:  'POST',
      headers: {
        'Authorization': `Bearer ${env.MAILGRID_KEY}`,
        'Content-Type':  'application/json',
        'Idempotency-Key': `swell-${event.type}-${event.data?.id}`,
      },
      body: JSON.stringify(payload),
    });

    return new Response('ok');
  }
};

Environment variables

Supported events

• order.created — order confirmation
• order.updated — status change (shipped, cancelled)
• order.payment_succeeded — payment received notice
• order.refunded — refund receipt
• account.created — new customer welcome
• account.request_recovery — password recovery email
• subscription.created — subscription welcome (for subscription products)
• subscription.renewal_succeeded — subscription renewal receipt

Vendure

The Vendure integration is a NestJS plugin that subscribes to OrderStateTransitionEvent and other Vendure events via the EventBus. It wires cleanly into Vendure's DI container and can replace or supplement the built-in EmailPlugin.

Setup

1. Install the plugin package:
   terminal

   npm install @mailgrid/vendure-plugin

2. Register the plugin in your Vendure config:
   vendure-config.ts

   import { MailgridPlugin } from '@mailgrid/vendure-plugin';
   
   export const config: VendureConfig = {
     plugins: [
       MailgridPlugin.init({
         apiKey:     process.env.MAILGRID_KEY!,
         fromAddress: process.env.MAILGRID_FROM!,
         streamId:    process.env.MAILGRID_STREAM_ID,
         templates: {
           orderConfirmation: process.env.MAILGRID_ORDER_TEMPLATE,
           shipping:          process.env.MAILGRID_SHIP_TEMPLATE,
           customerWelcome:   process.env.MAILGRID_WELCOME_TEMPLATE,
         },
       }),
     ],
   };

Key configuration

import { Injectable, OnModuleInit } from '@nestjs/common';
import { EventBus, OrderStateTransitionEvent } from '@vendure/core';
import { MailgridClient } from './mailgrid.client';

@Injectable()
export class MailgridEventHandler implements OnModuleInit {

  constructor(
    private eventBus: EventBus,
    private client:   MailgridClient,
  ) {}

  onModuleInit() {
    this.eventBus
      .ofType(OrderStateTransitionEvent)
      .subscribe(async (event) => {
        const { order, toState } = event;
        if (toState === 'PaymentSettled') {
          await this.client.send('orderConfirmation', order);
        } else if (toState === 'Shipped') {
          await this.client.send('shipping', order);
        } else if (toState === 'Cancelled') {
          await this.client.send('orderCancelled', order);
        }
      });
  }
}

Environment variables

Supported events

• OrderStateTransitionEvent → PaymentSettled — order confirmation
• OrderStateTransitionEvent → Shipped — shipping notification
• OrderStateTransitionEvent → Cancelled — cancellation notice
• OrderStateTransitionEvent → Refunded — refund receipt
• AccountRegistrationEvent — new customer welcome + email verification
• PasswordResetEvent — password reset email
• IdentifierChangeRequestEvent — email address change confirmation

CS-Cart

The CS-Cart integration is a PHP addon compatible with CS-Cart and Multi-Vendor 4.x. It uses CS-Cart's addon hook system to intercept order placement, status changes, and user registration events before the platform sends mail, replacing the default fn_send_mail() call with a direct Mailgrid API request.

Setup

1. Upload and install the addon:
   terminal

   # Archive the addon directory
   cd integrations/cs-cart
   zip -r mailgrid_transport.zip app design
   # Then upload via Admin → Add-ons → Manage Add-ons → Upload

2. In the CS-Cart admin, navigate to Add-ons → Manage Add-ons, find Mailgrid Transport, and set the status to Active.
3. Click the gear icon next to the addon and enter your Mailgrid API key, from-address, and template mappings.

Key configuration

function fn_mailgrid_transport_send_order_notification(array &$order_info,
                                                         string $event_id): void {
    $api_key  = Registry::get('addons.mailgrid_transport.api_key');
    $from     = Registry::get('addons.mailgrid_transport.from_address');
    $template = Registry::get("addons.mailgrid_transport.template_{$event_id}");

    $payload = [
        'from'        => $from,
        'to'          => $order_info['email'],
        'subject'     => __('order_placed_subject') . ' #' . $order_info['order_id'],
        'templateId'  => $template ?: null,
        'variables'   => [
            'orderId'   => $order_info['order_id'],
            'firstName' => $order_info['firstname'],
            'total'     => fn_format_price($order_info['total']),
        ],
    ];

    fn_mailgrid_post($api_key, $payload);
}

// Hook registered in addon init:
// fn_register_hooks('place_order_post', 'change_order_status_post', 'create_profile_post');

Environment variables

Supported events

• place_order_post — order confirmation email
• change_order_status_post — status change notification (shipped, cancelled, refunded)
• create_profile_post — new user registration welcome
• update_profile_post (password-change variant) — password updated notice
• Full fn_send_mail() intercept when override is enabled

nopCommerce

The nopCommerce integration is a C# plugin targeting .NET 7 / nopCommerce 4.60+. It implements IEmailSender and registers itself via the plugin's Services layer so that all outbound mail — orders, account notifications, newsletters — is dispatched through Mailgrid without any template changes required.

Setup

1. Copy the plugin into your nopCommerce installation:
   terminal

   cp -r integrations/nopcommerce/Mailgrid.Nop.Plugin \
          Plugins/Mailgrid.Nop.Plugin
   dotnet build Plugins/Mailgrid.Nop.Plugin -c Release

2. Restart the nopCommerce application. The plugin appears under Configuration → Local Plugins.
3. Click Install, then Configure. Enter your Mailgrid API key, from-address, and optional stream ID.
4. Under Configuration → Email Accounts, set the email account type to Mailgrid.

Key configuration

using Nop.Services.Messages;
using System.Net.Http.Json;

namespace Mailgrid.Nop.Plugin.Services;

public class MailgridEmailSender : IEmailSender
{
    private readonly MailgridSettings   _settings;
    private readonly HttpClient         _http;

    public MailgridEmailSender(MailgridSettings settings, IHttpClientFactory factory)
    {
        _settings = settings;
        _http     = factory.CreateClient("mailgrid");
        _http.DefaultRequestHeaders.Add(
            "Authorization", $"Bearer {settings.ApiKey}");
    }

    public async Task SendEmailAsync(
        EmailAccount emailAccount,
        string subject, string body,
        string fromAddress, string fromName,
        string toAddress,  string toName,
        string? replyTo = null,
        int delaySeconds = 0, string? attachmentFilePath = null,
        string? attachmentFileName = null,
        string? bodyEncoding = null)
    {
        var payload = new {
            from    = _settings.FromAddress,
            to      = toAddress,
            subject,
            html    = body,
            streamId = _settings.StreamId,
        };
        await _http.PostAsJsonAsync(
            "https://api.mailgrid.space/api/emails", payload);
    }
}

Environment variables

Supported events

• All emails dispatched through nopCommerce's IEmailSender — order placed, shipped, cancelled, refunded
• Customer registration welcome and email verification
• Password recovery
• Newsletter subscription confirmation
• Back-in-stock notifications
• Product review submitted confirmation
• Admin notification emails for new orders and registrations