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
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.
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.
fields and merge tags in details
We recommend using a fresh new audience, however, you can use any Audience list in your Mailchimp account.
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.
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.
Using your managerial permissions on your Mailchimp account, please generate a new API key for the integration. Go to Account > Extras > API key.
Once you generate the API key, we recommend saving it in a secure place so we can use it later.
Within your Pelcro's Dashboard, please find the "integration" icon on the left side menu.
Click on the Mailchimp icon
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.
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
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.
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.
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'.
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.
The integration will update John's Mailchimp profile and adds a new Event activity called customer_updated to his Activity Feed.
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.
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' ];
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' ];
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.
attached event data:
[ 'password_token' ];
event name: subscription_created
usage: This event is triggered when a new subscription has been created for a customer.
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.
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.
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.
event name: subscription_updated
usage: This event is triggered when the customer subscription has been updated.
event name: subscription_canceled
usage: This means this customer has canceled a subscription
event name: subscription_trialwillend
usage: This means the subscription's trial period will end in three days, or when a trial is ended immediately.
event name: subscription_renewed
usage: This means this customer has renewed their subscription.
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 ];
event name: invoice_created
usage: This means this customer has a new invoice
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.
event name: invoice_payment_succeeded
usage: This means the customer's attempt to pay an invoice was succeeded.
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) ];
event name: charge_succeeded
usage: This means the attempt of charging the customer succeeded and a charge is created.
event name: charge_failed
usage: This means the attempt of charging the customer failed.
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' ];
event name: source_expiring
usage: This means the customer's payment source or their card will expire at the end of the month.
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', ];
event name: address_created
usage: This means this customer has added a new address
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' ];
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.
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.
Then, click next to add a subject and sender information. Afterward, fill out all the Mailchimp requirements until you reach the Email Message Body.
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|"
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
Prepare your email message in your template
Use the button link from your Mailchimp toolbox on the right side of the screen
In the web address (URL) input, please add your website link.
Please click here
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
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
When you check this option, All of your end-users newsletter lists will be synced to MailChimp as MailChimp Tags.
When you check this option, All of your end-users newsletter lists will be synced to MailChimp as MailChimp Groups.
- 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.
If you exceed your MailChimp account limit without upgrading, the integration will automatically be de-activated.
Updated 1 day ago