MailChimp

The MailChimp integration allows businesses using Pelcro to send automated emails based on events happening on Pelcro. It allows you to leverage the power of both Pelcro and MailChimp without requiring any code and the setup will take you 10-15 mins. You can control the copy, branding, and call-to-actions while leveraging data fed from the integration. Below are all the steps required to get you started.

Create a MailChimp account

To use the integration you'll need an active Mailchimp account. To get started or to know more about the Mailchimp sign up process, please click here

Note: If you're already on Mailchimp you can just use your existing account.

Create a Mailchimp Audience


The first step to getting started with Mailchimp is setting up your audience. According to Mailchimp, your audience is where you’ll store and manage all your contact data. It's the bedrock of our integration.

Required Audience fields

Audience fields and MERGE tags MUST have the following three fields:
1- field first name and field merge tag is: FNAME - This will be updated with the customer's first name.
2- field last name and field merge tag is: LNAME - This will be updated with the customer's last name
3- field token and field merge tag is: TOKEN - This will be updated with a password reset token every time a user requests one. The token is required to be MERGE field in order to use it as a link in the email. This is due to the fact that MailChimp doesn't support using Event API fields while creating links.

4- field product name and field merge tag is: PRODNAME - This will be updated with the subscription's product name.
5- field plan name and field merge tag is: PLANNAME - This will be updated with the subscription's plan name.
6- field coupon code and field merge tag is: COUPONCODE - This will be updated with the subscription's coupon code.
7- field customer ID and field merge tag is: CUSTOMERID - This will be updated with the customer ID.
8- field subscription ID and field merge tag is: SUBID - This will be updated with the subscription ID.
9- field gift start date and field merge tag is: GIFTSTARTD - This will be updated with the gift subscription start date.
10- field is gift and field merge tag is: ISGIFT - This will be updated with whether the subscription is a gift or not.
11- field address id and field merge tag is: ADDRID - This will be updated with the address ID.
12- field address first name and field merge tag is: ADDRFNAME - This will be updated with the address first name.
13- field address last name and field merge tag is: ADDRLNAME - This will be updated with the address last name.
14- field address line 1 and field merge tag is: ADDRLINE1 - This will be updated with the address line 1.
15- field address city and field merge tag is: ADDRCITY - This will be updated with the address city.
16- field address state and field merge tag is: ADDRSTATE - This will be updated with the address state.
17- field address country and field merge tag is: ADDRCNTRY - This will be updated with the address country.
18- field address postal code and field merge tag is: ADDRPC - This will be updated with the address postal code.
19- field subscription status and field merge tag is: SUBSTATUS - This will be updated with the subscription status.
20- field subscription current period start and field merge tag is: SUBCURSTRT - This will be updated with the subscription current period start date.
21- field subscription current period end and field merge tag is: SUBCUREND - This will be updated with the subscription current period end date.
22- field subscription created at and field merge tag is: SUBCREATED - This will be updated with the subscription created date.
23- field subscription cancel at period end and field merge tag is: CNCLATEND - This will be updated with subscription cancel at period end (based on whether the subscription will end (value:1) or not (value:0)).

fields and merge tags in details

21442144 27242724

Can I use my existing Mailchimp Audience?

We recommend using a fresh new audience, however, you can use any Audience list in your Mailchimp account.

Get your Audience list ID

We'll need the Audience list ID from your MailChimp account. You can easily get it in five steps by clicking this link. After getting your list ID please save it in a secured place as we're going to use it in the integration.

Note the following requirements:

1- The selected audience list must have the three fields mentioned above.
2- The integration will overwrite any existing member's first name and last name.
3- The token will be updated with the latest token requested by the customer.

More information:

1- Create a Mailchimp Audience
2- Getting started with Mailchimp merge tags

Generate a Mailchimp API key

Using your managerial permissions on your Mailchimp account, please generate a new API key for the integration. Go to Account > Extras > API key.

For more details, please check out the link below:

1- Generate a new API key.

What's next?

Once you generate the API key, we recommend saving it in a secure place so we can use it later.

Now, log in to your Pelcro account


Pelcro Dashboard

Within your Pelcro's Dashboard, please find the "integration" icon on the left side menu.

24882488

click on integrations

Integrations

Click on the Mailchimp icon

32643264

click on the mailchimp integration

Mailchimp Integration

29962996

What's next?

Just add the API key and the Audience List-ID that we've created earlier in this documentation, and click the ADD NEW green button.

Please note:

1- You'll not be able to restore or read the full API key string after clicking 'ADD NEW' As we masked it following our security protocols.
2- We'll show the last four characters of the API key unmasked so you can recognize it.
3- If you clicked 'DELETE KEYS', this will deactivate the integration immediately.
4- To reactivate the integration one more time you'll have to add your API key and Audience List ID as described above.
5- There is a limitation that the request will generate an error from MailChimp if the length exceeded 1000 characters. To help abide by this limit, we added the 'Excluded Metadata keys' field in the integration page that will allow you to omit multiple end-user metadata fields from those requests that you might find useless or redundant in MailChimp.
6- You can select "Sync newsletters into MailChimp" and this will sync all newsletters that are created in Pelcro with MailChimp.

  • Creating a newsletter for an email will create or update the customer on Mailchimp and the lists will be synced into tags
  • The customer will be added to the same audience list provided in the integration

Before we go back to MailChimp

Now, we assume/hope that everything went well so far till this point. Before we get back to Mailchimp please use your Pelcro account to create a test customer. This way we can walk you through the next steps of using the best of the integration features.

29962996 32703270 32883288

Now it's the Time to get back to Mailchimp


Go to your Mailchimp account and open the Audience List that you used with our integration. You'll find that the user John Doe has been added to your LIST automatically.

26822682

Breakdown of the process

Mailchimp API custom events

We're using the most up-to-date Mailchimp feature called API CUSTOM EVENTS. With this feature, we're not just adding your Pelcro's customers to your Mailchimp Audience but also we're continuously updating their Mailchimp profiles with "Events activity'.

What exactly are Events Activities?

Each time any of your customers do something on Pelcro, we add a new Event activity to their profile on Mailchimp. Activity data will be handy and you can build emails, statistics, and different feedbacks on top of it.

John updated his first name to Johnson.

The integration will update John's Mailchimp profile and adds a new Event activity called customer_updated to his Activity Feed.

20382038

Johnson created his first subscription

The integration will add a new Event activity called subscription_created to Johnson's Mailchimp profile. Inside this activity, you'll find all the necessary information that's related to the new subscription that Johnson created. In addition, you'll find all the details of the subscription below.

17101710

Now, Let's map out our Events


CUSTOMER CREATED

event name: customer_created
usage: This event is triggered when a new customer record has been created.
attached event data:

[
  'first_name',
  'last_name',
  'email'
];

CUSTOMER UPDATED

event name: customer_updated
usage: This event is triggered when an existing customer record has been updated.
attached event data:

[
  'first_name',
  'last_name',
  'email'
];

CUSTOMER PASSWORD RESET

event name: customer_reset_password
usage: This event is triggered when the customer has requested a password reset. As part of the password reset email being sent out to the customer, you will need to include the password token. Below is an example of how you should build the link based on the user email and the password token.
example: https://www.yourdomain.com?view=password-reset&email=*|EMAIL|*&token=*|TOKEN|*
attached event data:

[
   'password_token'
];

SUBSCRIPTION CREATED

event name: subscription_created
usage: This event is triggered when a new subscription has been created for a customer.

SUBSCRIPTION GIFT DONOR

event name: subscription_gift_donor
usage: This event is triggered when a donor has purchased a gift subscription for a recipient. You can use it to build logic around sending emails to donors.

SUBSCRIPTION GIFT RECIPIENT

event name: subscription_gift_recipient
usage: This event is also triggered when a donor has purchased a gift subscription for a recipient. You can use it to send an email to the recipient with their gift code.

SUBSCRIPTION GIFT NOTIFICATION

event name: subscription_gift_notification
usage: This event is triggered on the date specified by the donor during the gift creation process. You can use this to send an email to the recipient with their gift code. The "SUBSCRIPTION GIFT RECIPIENT" and "SUBSCRIPTION GIFT NOTIFICATION" contain the same data, except the later is triggered based on the date specified by the donor while the other is triggered upon purchase.

SUBSCRIPTION UPDATED

event name: subscription_updated
usage: This event is triggered when the customer subscription has been updated.

SUBSCRIPTION CANCELED

event name: subscription_canceled
usage: This means this customer has canceled a subscription

SUBSCRIPTION TRIAL WILL END

event name: subscription_trialwillend
usage: This means the subscription's trial period will end in three days, or when a trial is ended immediately.

SUBSCRIPTION RENEWED

event name: subscription_renewed
usage: This means this customer has renewed their subscription.

SUBSCRIPTION EXPIRED

event name: subscription_expired
usage: This means this customer's subscription was expired.

subscription events' data:

[
  'id',
  'site_id',
  'address_id',
  'backdate_start_date',
  'billing',
  'billing_cycle_anchor',
  'cancel_at',
  'cancel_at_period_end',
  'canceled_at',
  'cancel_reason',
  'created',
  'current_period_end',
  'current_period_start',
  'coupon_name', // Present when using a coupon
  'coupon_code', // Present when using a coupon
  'coupon_percent_off', // Present when using a coupon
  'days_until_due',
  'ended_at',
  'quantity',
  'shipments_remaining',
  'source',
  'status',
  'trial_end',
  'trial_start',
  'shipments_undeliverable',
  'shipments_suspended_until',
  'is_gift_donor',
  'is_gift_recipient',
  'gift_code',
  'is_redeemed',
  'gift_recipient_email',
  'gift_recipient_first_name',
  'gift_recipient_last_name',
  'gift_start_date',
  'gift_message',
  'gift_donor_subscription_id',
  'agency_id',
  'updated_at',
  'latest_invoice_id',
  'subscription_plan', // Plan name
  'subscription_product', // Product name
  'donor_first_name', //optional with gift subscriptions notifications
  'donor_last_name',//optional with gift subscriptions notifications
  'donor_email'//optional with gift subscriptions notifications
];

INVOICE CREATED

event name: invoice_created
usage: This means this customer has a new invoice

INVOICE UPCOMING

event name: invoice_upcoming
usage: This event will be generated an X number of days (configurable on the Pelcro platform) before a subscription is about to renew.

INVOICE PAYMENT SUCCEEDED

event name: invoice_payment_succeeded
usage: This means the customer's attempt to pay an invoice was succeeded.

INVOICE PAYMENT FAILED

event name: invoice_payment_failed
usage: This means the customer's attempt to pay an invoice was FAILED.

invoice events' data:

[
  'id',
  'amount_due',
  'amount_paid',
  'amount_remaining',
  'billing',
  'billing_reason',
  'currency',
  'created',
  'coupon_name', // Present when using a coupon
  'coupon_code', // Present when using a coupon
  'coupon_percent_off', // Present when using a coupon
  'ending_balance',
  'finalized_at',
  'invoice_pdf',
  'marked_uncollectible_at',
  'paid_at',
  'period_end',
  'period_start',
  'post_payment_credit_notes_amount',
  'pre_payment_credit_notes_amount',
  'starting_balance',
  'status',
  'total',
  'voided_at',
  'updated_at',
  'number',
  'amount_due_in_major_unit', // Money amount in the major currency unit ( cents / 100)
  'amount_paid_in_major_unit', // Money amount in the major currency unit ( cents / 100)
  'amount_remaining_in_major_unit', // Money amount in the major currency unit ( cents / 100)
  'total_in_major_unit', // Money amount in the major currency unit ( cents / 100)
];

CHARGE SUCCEEDED

event name: charge_succeeded
usage: This means the attempt of charging the customer succeeded and a charge is created.

CHARGE FAILED

event name: charge_failed
usage: This means the attempt of charging the customer failed.

CHARGE REFUNDED

event name: charge_refunded
usage: This means the attempt of refunding a charge to the customer was succeeded and the customer was refunded.

charge events' data:

[
  'id',
  'user_id',
  'invoice_id',
  'payment_intent_id',
  'source_id',
  'amount',
  'amount_refunded',
  'created',
  'currency',
  'disputed',
  'failure_code',
  'failure_message',
  'offline',
  'offline_entered_by',
  'order',
  'origin',
  'paid',
  'reference',
  'refunded',
  'status',
  'refunded_at',
  'origin',
  'deleted_at',
  'remit_rate',
  'remit_rate_amount',
  'amount_in_major_unit'
];

SOURCE EXPIRING

event name: source_expiring
usage: This means the customer's payment source or their card will expire at the end of the month.

SOURCE CANCELED

event name: source_canceled
usage: This means the customer's payment source or their card is canceled.

source events' data:

[
  'exp_month',
  'exp_year',
  'address_zip_check',
  'brand',
  'country',
  'cvc_check',
  'funding',
  'last4',
  'name',
  'address_line1_check',
  'dynamic_last4',
];

ADDRESS CREATED

event name: address_created
usage: This means this customer has added a new address

ADDRESS UPDATED

event name: address_updated
usage: This means this customer has updated their address
address events' data:

[
  'id',
  'type',
  'first_name',
  'last_name',
  'line1',
  'line2',
  'city',
  'state',
  'country',
  'postal_code',
  'created_at',
  'updated_at'
];

MEMBER CREATED

event name: member_created
usage: This means that a new member was created

MEMBER UPDATED

event name: member_updated
usage: This means this member information has been updated
member events' data:

[
    'id',
    'status',
    'site_id',
    'user_id',
    'address_id',
    'subscription_id',
    'invitation_email',
    'plan_id',
        'plan_amount',
        'plan_currency',
        'plan_interval',
        'plan_interval_count',
        'plan_nickname',
        'plan_name_internal',
        'product_id',
        'product_description',
        'product_name',
        'product_name_internal',
        'subscription_id',
        'subscription_cancel_at_period_end',
        'subscription_current_period_end',
        'subscription_current_period_start'
];

Finally, let's send a notification


Let's use what we learned so far to send a subscription confirmation email. It will be sent automatically once the user creates their new subscription on Pelcro.

Go to automate and click on the Email link

17341734

Now, select API, and then Event API

24402440

Name your email campaign

21682168

Click edit the trigger

32783278

Now copy the event "subscription_created" and add it as the event name and click update trigger

14601460

Please note

1- You must copy the event's name from this document.
2- Note that you have all the events and their data properties
3- You must paste the custom event name in the event name field as shown below.
4- Formating the event data attributes may not work according to some of our tests "|EVENT:subscription_product|" - please avoid formatting the event attributes.

32623262

Then, click next to add a subject and sender information. Afterward, fill out all the Mailchimp requirements until you reach the Email Message Body.

Customize your email using merge tags and event merge tags

To access any of the subscription created event data (which we listed above), you can easily use it inside the Email body as shown in the picture below. "|EVENT:subscription_plan|"

32883288

Email will look like this:

16401640

Sample email for the subscription_created event.

Hey *|FNAME|*, 

Thank you for subscribing to the following:

Product: *|EVENT:subscription_product|*
Plan: *|EVENT:subscription_plan|*
Start date: *|EVENT:current_period_start|*
End date: *|EVENT:current_period_end|*

Please reply to this email if you have any questions.

Thanks,

Business Name

Use merge tags to generate personalized links

Email template

Prepare your email message in your template

32883288

Add link

Use the button link from your Mailchimp toolbox on the right side of the screen

792792

Select Web Address

In the web address (URL) input, please add your website link.

10501050

EX: http://example.com/?view=password-reset&email=*|EMAIL|*&token=*|TOKEN|*

10401040

Click insert and the link will be ready

28002800

More information

Please click here

Mailchimp API Custom event video tutorial

If you couldn't apply the previous example or for any reason you want more information, we recommend visiting the Mailchimp API custom event video tutorial. It's a great help in learning how to use and implement automated emails using API custom events.

For the Mailchimp API CUSTOM EVENT please click here

Mailchimp webhook support

Pelco's Mailchimp integration is now capable of generating a unique webhook URI per account, With a hashed unique URIs you can sync back all the Mailchimp list unsubscribes to your Pelcro's integration.

For the Mailchimp webhooks please click here

23602360

Sync Pelcro newsletter lists as Tags

When you check this option, All of your end-users newsletter lists will be synced to MailChimp as MailChimp Tags.

14401440

Sync Pelcro newsletter lists as Groups

When you check this option, All of your end-users newsletter lists will be synced to MailChimp as MailChimp Groups.

Please note

  • This option will create a group and an interest with the newsletter list name, Incase the group name doesn't exist on your audience list.
  • The end-user will be assigned/unassigned automatically in MailChimp groups based on their newsletter lists.
16301630

Limitations

Maximum number of members in the audience list

If you exceed your MailChimp account limit without upgrading, the integration will automatically be de-activated.



Did this page help you?