@input-output-hk/mailchimp-subscribe

Mailchimp subscribe library

An internationalization friendly mailchimp subscribe library. Subscribe emails to your mailing lists.

Contents

1. Features
2. Install
3. Finding mailchimp values
4. Examples
5. Contributing

Features

• Error codes and success codes for i18n
• Custom fields

Install

npm install --save @input-output-hk/mailchimp-subscribe

or

yarn add @input-output-hk/mailchimp-subscribe

Finding Mailchimp values

Finding the 'uID' value

Finding the 'audienceID' value

Finding the 'listName' value

Examples

Basic supporting localization

import subscribe, { SUCCESS_CODES, ERROR_CODES } from '@input-output-hk/mailchimp-subscribe'

async function submitForm (email) {
  try {
    const result = await subscribe({
      email,
      uID: 'XXXXXXXXX',
      audienceID: 'XXXXXXXXX',
      listName: 'XXXXXX.XXXX'
    })

    const successCode = result.getCode()
    switch (successCode) {
      case SUCCESS_CODES.CONFIRM_EMAIL_ADDRESS:
        // Successfully subscribed, user needs to confirm email
        return '' // Use the code to return a localized string message
      case SUCCESS_CODES.GENERIC:
        // Successfully subscribed, default code
        return '' // Use the code to return a localized string message
    }
  } catch (error) {
    // Original message returned from mailchimp
    const message = error.message
    const errorCode = error.getCode()

    switch (successCode) {
      case ERROR_CODES.INVALID_EMAIL:
        // Email invalid
        return '' // Use the code to return a localized string message

      case ERROR_CODES.INVALID_EMAIL_DOMAIN:
        // Domain section of email invalid
        return '' // Use the code to return a localized string message

      case ERROR_CODES.INVALID_EMAIL_USERNAME:
        // Username section of email invalid
        return '' // Use the code to return a localized string message

      case ERROR_CODES.EMAIL_ALREADY_SUBSCRIBED:
        // Email is already subscribed to mailing list
        // Additional context is available here
        // Link to manage the subscription for the email address
        const manageSubscriptionLink = error.getContext().manageSubscriptionLink
        return '' // Use the code to return a localized string message

      case ERROR_CODES.TIMEOUT:
        // Request timed out
        return '' // Use the code to return a localized string message

      case ERROR_CODES.GENERIC:
        // Generic error code, server errors etc.
        return '' // Use the code to return a localized string message
    }
  }
}

Basic without localization

import subscribe from '@input-output-hk/mailchimp-subscribe'

async function submitForm (email) {
  try {
    await subscribe({
      email,
      uID: 'XXXXXXXXX',
      audienceID: 'XXXXXXXXX',
      listName: 'XXXXXX.XXXX'
    })

    return true
  } catch (error) {
    // handle error
    // error.message is the message returned from Mailchimp if the error originated on mailchimp
    return false
  }
}

Custom fields

import subscribe from '@input-output-hk/mailchimp-subscribe'

async function submitForm (email) {
  try {
    await subscribe({
      email,
      uID: 'XXXXXXXXX',
      audienceID: 'XXXXXXXXX',
      listName: 'XXXXXX.XXXX',
      customFields: {
        MY_FIELD: 'value',
        MY_SECOND_FIELD: 'value_2'
      }
    })

    return true
  } catch (error) {
    // handle error
    // error.message is the message returned from Mailchimp if the error originated on mailchimp
    return false
  }
}

Specifiying a timeout

import subscribe from '@input-output-hk/mailchimp-subscribe'

async function submitForm (email) {
  try {
    await subscribe({
      email,
      uID: 'XXXXXXXXX',
      audienceID: 'XXXXXXXXX',
      listName: 'XXXXXX.XXXX',
      // 6000ms
      timeout: 6000
    })

    return true
  } catch (error) {
    // handle error
    // error.message is the message returned from Mailchimp if the error originated on mailchimp
    return false
  }
}

Contributing

Contributions are welcome, see contributing for more info.