Skip to main content

Mailchimp

In this document, you’ll learn about the Mailchimp plugin, what it does, and how to use it.

Overview​

Mailchimp is an email marketing service that can be used to create newsletters and subscriptions.

By integrating Mailchimp with Medusa, customers will be able to subscribe from Medusa to your Mailchimp newsletter and will be automatically added to your Mailchimp subscribers list.

This plugin is only used to allow your customers to subscribe but does not actually do any email sending. If you want to send emails to customers based on specific events, for example, when an order is placed, you should check out the SendGrid plugin instead.

Prerequisites​

Before going further with this guide make sure you have a Medusa server set up. You can follow the Quickstart guide.

You also need a Mailchimp account, so please create one before you start.

Obtain Mailchimp Keys​

To integrate the plugin into Medusa you need two keys: The API Key and the Newsletter list or Audience ID. The API Key acts as a credential for your account, whereas the Newsletter list ID determines which audience should the subscribed customers be added to.

You can follow this guide from Mailchimp’s documentation to obtain an API Key.

You can follow this guide from Mailchimp’s documentation to obtain your Newsletter list or Audience ID.

Install the Plugin​

In the directory of your Medusa server, run the following command to install the Mailchimp plugin:

yarn add medusa-plugin-mailchimp
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

Add Keys​

Open .envCopy to Clipboard and add the following keys:

MAILCHIMP_API_KEY=<YOUR_API_KEY>
MAILCHIMP_NEWSLETTER_LIST_ID=<YOUR_NEWSLETTER_LIST_ID>
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

Make sure to replace <YOUR_API_KEY>Copy to Clipboard with your API Key and <YOUR_NEWSLETTER_LIST_ID>Copy to Clipboard with your Newsletter list or Audience ID.

Add Plugin to Medusa Config​

Open medusa-config.jsCopy to Clipboard and add the new plugin into the pluginsCopy to Clipboard array:

medusa-config.js
const plugins = [
  // ...,
  {
    resolve: `medusa-plugin-mailchimp`,
    options: {
      api_key: process.env.MAILCHIMP_API_KEY,
      newsletter_list_id: process.env.MAILCHIMP_NEWSLETTER_LIST_ID,
    },
  },
]
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

Test it Out​

This plugin adds a new POSTCopy to Clipboard endpoint at /mailchimp/subscribeCopy to Clipboard. This endpoint requires in the body of the request an emailCopy to Clipboard field. You can also optionally include a dataCopy to Clipboard object that holds any additional data you want to send to Mailchimp. You can check out Mailchimp’s subscription documentation for more details on the data you can send.

Without Additional Data​

Try sending a POSTCopy to Clipboard request to /mailchimp/subscribeCopy to Clipboard with the following JSON body:

{
  "email": "example@gmail.com"
}
Copy to ClipboardCopy to Clipboard

If the subscription is successful, a 200Copy to Clipboard response code will be returned with OKCopy to Clipboard message.

Postman

If you check your Mailchimp dashboard, you should find the email added to your Audience list.

Email Added

With Additional Data​

Here’s an example of sending additional data with the subscription:

{
    "email": "example@gmail.com",
    "data": {
        "tags": ["customer"]
    }
}
Copy to ClipboardCopy to Clipboard

All fields inside dataCopy to Clipboard will be sent to Mailchimp’s API along with the email.

Use Mailchimp Service​

If you want to subscribe to users without using this endpoint or at a specific place in your code, you can use Mailchimp’s service mailchimpServiceCopy to Clipboard in your endpoints, services, or subscribers. This service has a method subscribeNewsletterCopy to Clipboard which lets you use the subscribe functionality.

Here’s an example of using the mailchimpServiceCopy to Clipboard inside an endpoint:

src/api/index.ts
const mailchimpService = req.scope.resolve("mailchimpService")

mailchimpService.subscribeNewsletter(
  "example@gmail.com",
  { tags: ["customer"] } // optional
)
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

You can learn more about how you can use services in your endpoints, services, and subscribers in the Services documentation.

Add Subscription Form​

This section has a simple example of adding a subscription form in your storefront. The code is for React-based frameworks but you can use the same logic for your storefronts regardless of the framework you are using.

You’ll need to use axios to send API requests, so if you don’t have it installed make sure you install it first:

yarn add axios
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

Then, in the component you want to add the subscription form add the following code:

import axios from "axios"
import { useState } from "react"

export default function NewsletterForm() {
  const [email, setEmail] = useState("")

  function subscribe(e) {
    e.preventDefault()
    if (!email) {
      return
    }

    axios.post("http://localhost:9000/mailchimp/subscribe", {
      email,
    })
      .then((e) => {
        alert("Subscribed sucessfully!")
        setEmail("")
      })
      .catch((e) => {
        console.error(e)
        alert("An error occurred")
      })
  }

  return (
    <form onSubmit={subscribe}>
      <h2>Sign Up for our newsletter</h2>
      <input 
        type="email" name="email" id="email" 
        placeholder="example@gmail.com"
        value={email} onChange={(e) => setEmail(e.target.value)} />
      <button type="submit">Subscribe</button>
    </form>
  )
}
Report Incorrect CodeReport Incorrect CodeCopy to ClipboardCopy to Clipboard

This will result in a subscription form similar to the following:

Subscription Form

If you try entering an email and clicking Subscribe, the email will be subscribed to your Mailchimp newsletter successfully.

See Also​