Integration Module 2.0 for Medusa is outRead the announcement
Bloomreach logo

Bloomreach

Send notifications and track engagement

npm install @igorppbr/medusa-v2-bloomreach
Category
Service
Version
1.0.0
Last updated
11 months ago
Monthly downloads
Loading downloads

Bloomreach logo

Bloomreach Engagement Integration for Medusa v2

API Documentation | Bloomreach Website

PRs welcome! Follow me on LinkedIn

Introduction

This module integrates Bloomreach (Exponea) as a notification and analytics provider for Medusa v2. It enables you to send transactional emails and SMS messages through the Bloomreach platform, as well as track customer events and behavior for powerful engagement and marketing automation.

With this plugin, you can:

  • Send transactional emails using Bloomreach email templates or custom content.
  • Send transactional SMS messages using Bloomreach SMS templates or raw text.
  • Track customer events and behavior for analytics and personalization.
  • Personalize notifications with dynamic data and customer information.
  • Monitor notification delivery and engagement through Bloomreach analytics.
  • Manage campaigns and templates directly in the Bloomreach dashboard.

Compatibility

This module/plugin is compatible with versions >= 2.4.0 of .

Prerequisites

Before using this integration, you need:

  1. A Bloomreach (Exponea) account - Sign up at Bloomreach
  2. API credentials - You'll need:
    • API Key ID - Found in your Bloomreach project settings
    • API Secret - Found in your Bloomreach project settings
    • Project ID - Your Bloomreach project identifier
    • Integration ID - The ID of your email/SMS service provider integration

Getting Your Bloomreach Credentials

  1. Log in to Bloomreach at https://app.exponea.com/
  2. Navigate to Project Settings → Access Management → API
  3. Create a new API key (or use an existing one):
    • Assign permissions: Campaigns > Transactional Email API, Campaigns > Transactional SMS API, and Events > Set
    • Note down your Key ID and Secret
  4. Find your Project ID:
    • Available in the URL when logged into your project
    • Format:
  5. Get your Integration ID:
    • Go to Project Settings → Channels → Email/SMS
    • Select your email or SMS integration
    • Copy the Integration ID from the URL or settings page

For more details, see the Bloomreach Authentication Documentation.

Installation

  1. Install the package
  1. Add the module to your

Note: Adding the plugin is required for Medusa to load the event subscribers that handle notifications and analytics tracking.

  1. Add environment variables to your file

Important: Never commit your API credentials to version control. Always use environment variables.

Configuration Options

OptionTypeRequiredDescription
stringYesYour Bloomreach API Key ID
stringYesYour Bloomreach API Secret
stringYesYour Bloomreach Project ID
stringYesYour email/SMS integration ID
stringYesDefault sender email address
stringYesDefault sender name for emails
stringConditionalRequired if using SMS channel - sender phone number
stringNoDefault language code (e.g., "en", "es")
stringNoLink tracking behavior: "enabled", "disabled", or "first_click"
objectNoMap Medusa template names to Bloomreach template IDs
objectNoMap template names to campaign names

Usage

Tracking Customer Events (Analytics)

Track customer behavior and events for analytics and personalization:

Example: Tracking Order Events

Create a workflow to track order events:

Then create a subscriber to execute the workflow:

Sending Email Notifications

Once configured, you can send email notifications using the Notification Module:

Sending SMS Notifications

Example: Order Confirmation Subscriber

Create a subscriber to send order confirmation emails:

Template Setup in Bloomreach

  1. Log in to Bloomreach and navigate to Campaigns → Email/SMS Templates
  2. Create a new template or use an existing one
  3. Note the Template ID from the URL or template settings
  4. Add personalization variables in your template using Jinja syntax:
  5. Map the template in your using

Features

Analytics Features

  • ✅ Track custom events and user behavior
  • ✅ Customer journey tracking
  • ✅ Event properties and metadata
  • ✅ Real-time event processing
  • ✅ Integration with Bloomreach Engagement

Email Features

  • ✅ Template-based emails with personalization
  • ✅ Custom sender name and address
  • ✅ Multi-language support
  • ✅ Link tracking and analytics
  • ✅ Campaign management

SMS Features

  • ✅ Template-based SMS with personalization
  • ✅ Raw text SMS messages
  • ✅ Multi-language support
  • ✅ Configurable message parts (1-8)
  • ✅ Campaign tracking

Troubleshooting

Common Issues

Error: "API key is required in the provider's options"

  • Make sure all required environment variables are set in your file
  • Verify that your correctly references the environment variables

Error: "From SMS is required in the provider's options to send SMS notifications"

  • Add the option to your configuration if you're using the SMS channel

Email/SMS not being sent

  • Check that your Bloomreach API credentials have the correct permissions
  • Verify that your Integration ID is correct
  • Check the Medusa logs for detailed error messages
  • Ensure your templates exist in Bloomreach and template IDs are correct

Template not found

  • Verify the template ID in your configuration
  • Check that the template exists and is published in Bloomreach

API Reference

Bloomreach SDK Functions

This package includes a Bloomreach SDK with the following functions:

Sends a transactional email through Bloomreach.

Sends a transactional SMS through Bloomreach.

Tracks a customer event in Bloomreach.

Contributing

We welcome contributions to this project! If you have suggestions, improvements, or bug fixes, please follow these steps:

  1. Fork the Repository
    Create a personal copy of the repository by forking it on GitHub.

  2. Create a New Branch
    Create a new branch for your changes:

  3. Make Your Changes
    Implement your changes in the codebase.

  4. Test Your Changes
    Ensure that your changes work as expected and do not break existing functionality.

  5. Submit a Pull Request
    Push your changes to your forked repository and submit a pull request to the main repository.

Support / Contact

If you need help or have questions about the Bloomreach Engagement Integration, please reach out to us:

License

This project is licensed under the MIT License.


Additional Resources