Home

Awesome

Manage Marketing with Mailchimp

Author: Mailchimp (https://mailchimp.com)

Description: Syncs user data with a Mailchimp audience for sending personalized email marketing campaigns.

Details: Use this extension to:

Additional setup

Make sure that you've set up Firebase Authentication to manage your users.

You must also have a Mailchimp account before installing this extension.

Billing

This extension uses the following Firebase services which may have associated charges:

This extension also uses the following third-party services:

You are responsible for any costs associated with your use of these services.

Note from Firebase

To install this extension, your Firebase project must be on the Blaze (pay-as-you-go) plan. You will only be charged for the resources you use. Most Firebase services offer a free tier for low-volume use. Learn more about Firebase billing.

You will be billed a small amount (typically less than $0.10) when you install or reconfigure this extension. See the Cloud Functions for Firebase billing FAQ for a detailed explanation.

Configuration Parameters:

Required Fields:

  1. memberTags - The Firestore document fields(s) to retrieve data from and classify as subscriber tags in Mailchimp. Acceptable data types include:

    • Array<String> - The extension will lookup the values in the provided fields and update the subscriber's member tags with the respective data values. The format of each string can be any valid JMES Path query. e.g. ["primaryTags", "additionalTags", "tags.primary"]

    • Array<Object> - An extended object configuration is supported with the following fields:

      • documentPath - (required) The path to the field in the document containing tag/s, as a string. The format can be any valid JMES Path query. e.g. "primaryTags", "tags.primary".

  2. subscriberEmail - The Firestore document field capturing the user email as is recognized by Mailchimp

Configuration Example:

{
  "memberTags": ["domainKnowledge", "jobTitle"],
  "subscriberEmail": "emailAddress"
}

Or via equivalent extended syntax:

{
  "memberTags": [{ "documentPath": "domainKnowledge" }, { "documentPath": "jobTitle" }],
  "subscriberEmail": "emailAddress"
}

Based on the sample configuration, if the following Firestore document is provided:

{
  "firstName": "..",
  "lastName": "..",
  "phoneNumber": "..",
  "courseName": "..",
  "emailAddress": "..", // The config property 'subscriberEmail' maps to this document field
  "jobTitle": "..", // The config property 'memberTags' maps to this document field
  "domainKnowledge": "..", // The config property 'memberTags' maps to this document field
  "activity": []
}

Any data associated with the mapped fields (i.e. domainKnowledge and jobTitle) will be considered Member Tags and the Mailchimp user's profile will be updated accordingly. For complex documents such as:

{
  "emailAddress": "..", // The config property 'subscriberEmail' maps to this document field
  "meta": {
    "tags": [{
      "label": "Red",
      "value": "red"
    },{
      "label": "Team 1",
      "value": "team1"
    }]
  }
}

A configuration of the following will allow for the tag values of "red", "team1" to be sent to Mailchimp:

{
  "memberTags": [{ "documentPath": "meta.tags[*].value" }],
  "subscriberEmail": "emailAddress"
}

NOTE: To disable this cloud function listener, provide an empty JSON config {}.

Required Fields:

  1. mergeFields - JSON mapping representing the Firestore document fields to associate with Mailchimp Merge Fields. The key format can be any valid JMES Path query as a string. The value must be the name of a Mailchimp Merge Field as a string, or an object with the following properties:

    • mailchimpFieldName - (required) The name of the Mailchimp Merge Field to map to, e.g. "FNAME". Paths are allowed, e.g. "ADDRESS.addr1" will map to an "ADDRESS" object.

    • typeConversion - (optional) Whether to apply a type conversion to the value found at documentPath. Valid options:

      • none: no conversion is applied.

      • timestampToDate: Converts from a Firebase Timestamp to YYYY-MM-DD format (UTC).

      • stringToNumber: Converts to a number.

    • when - (optional) When to send the value of the field to Mailchimp. Options are "always" (which will send the value of this field on any change to the document, not just this field) or "changed". Default is "changed".

  2. statusField - An optional configuration setting for syncing the users mailchimp status. Properties are:

    • documentPath - (required) The path to the field in the document containing the users status, as a string. The format can be any valid JMES Path query. e.g. "status", "meta.status".

    • statusFormat - (optional) Indicates the format that the status field is. The options are:

      • "string" - The default, this will sync the value from the status field as is, with no modification.
      • "boolean" - This will check if the value is truthy (e.g. true, 1, "subscribed"), and if so will resolve the status to "subscribed", otherwise it will resolve to "unsubscribed".

  3. subscriberEmail - The Firestore document field capturing the user email as is recognized by Mailchimp

Configuration Example:

{
  "mergeFields": {
    "firstName": "FNAME",
    "lastName": "LNAME",
    "phoneNumber": "PHONE"
  },
  "subscriberEmail": "emailAddress"
}

Or via equivalent extended syntax:

{
  "mergeFields": {
    "firstName": { "mailchimpFieldName": "FNAME" },
    "lastName":{ "mailchimpFieldName": "LNAME" },
    "phoneNumber": { "mailchimpFieldName": "PHONE", "when": "changed" }
  },
  "subscriberEmail": "emailAddress"
}

Based on the sample configuration, if the following Firestore document is provided:

{
  "firstName": "..", // The config property FNAME maps to this document field
  "lastName": "..", // The config property LNAME maps to this document field
  "phoneNumber": "..", // The config property PHONE maps to this document field
  "emailAddress": "..", // The config property "subscriberEmail" maps to this document field
  "jobTitle": "..", 
  "domainKnowledge": "..",
  "activity": []
}

Any data associated with the mapped fields (i.e. firstName, lastName, phoneNumber) will be considered Merge Fields and the Mailchimp user's profile will be updated accordingly. If there is a requirement to always send the firstName and lastName values, the "when": "always" configuration option can be set on those fields, like so:

{
  "mergeFields": {
    "firstName": { "mailchimpFieldName": "FNAME", "when": "always" },
    "lastName":{ "mailchimpFieldName": "LNAME", "when": "always" },
    "phoneNumber": { "mailchimpFieldName": "PHONE", "when": "changed" }
  },
  "subscriberEmail": "emailAddress"
}

This can be handy if Firebase needs to remain the source or truth or if the extension has been installed after data is already in the collection and there is a data migration period. If the users status is also captured in the Firestore document, the status can be updated in Mailchimp by using the following configuration:

{
  "statusField": {
    "documentPath": "meta.status",
    "statusFormat": "string",
  },
  "subscriberEmail": "emailAddress"
}

This can be as well, or instead of, the mergeFields configuration property being set. NOTE: To disable this cloud function listener, provide an empty JSON config {}.

Required Fields:

  1. memberEvents - The Firestore document fields(s) to retrieve data from and classify as member events in Mailchimp. Acceptable data types include:
  1. subscriberEmail - The Firestore document field capturing the user email as is recognized by Mailchimp

Configuration Example:

{
  "memberEvents": [
    "activity"
  ],
  "subscriberEmail": "emailAddress"
}

Or via equivalent extended syntax:

{
  "memberEvents": [{ "documentPath": "activity" }],
  "subscriberEmail": "emailAddress"
}

Based on the sample configuration, if the following Firestore document is provided:

{
  "firstName": "..",
  "lastName": "..",
  "phoneNumber": "..",
  "courseName": "..",
  "jobTitle": "..", 
  "domainKnowledge": "..",
  "emailAddress": "..", // The config property "subscriberEmail" maps to this document field
  "activity": ["send_welcome_email"] // The config property "memberTags" maps to this document field
}

Any data associated with the mapped fields (i.e. activity) will be considered events and the Mailchimp user's profile will be updated accordingly. For complex documents such as:

{
  "emailAddress": "..", // The config property 'subscriberEmail' maps to this document field
  "meta": {
    "events": [{
      "title": "Registered",
      "date": "2021-10-08T00:00:00Z"
    },{
      "title": "Invited Friend",
      "date": "2021-10-09T00:00:00Z"
    }]
  }
}

A configuration of the following will allow for the events of "Registered", "Invited Friend" to be sent to Mailchimp:

{
  "memberEvents": [{ "documentPath": "meta.events[*].title" }],
  "subscriberEmail": "emailAddress"
}

NOTE: To disable this cloud function listener, provide an empty JSON config {}.

Cloud Functions: