This page details our how software integrates with Customer.io. our Customer-relationship management (CRM) tool.
Overview
We maintain a Customer in Customer.io for each Northstar user. Any time a Northstar user is created or updated, Northstar creates or updates the corresponding Customer in Customer.io via API request.
We use Customer.io Events and Segments to send emails and SMS broadcasts to users.
-
Events are actions that users perform within our apps, e.g. creating an account, signing up for a campaign, or submitting a reportback.
- We use Event Triggered Campaigns to send users a message any time they perform a specific event (e.g. sending a confirmation email to a user upon signing up for a campaign, sending a password reset email to a user upon submitting the Forgot Password form).
-
Segments allow grouping users by attributes (e.g. all users in NY who are over 18) and/or who have taken actions (e.g. all users who signed up for Give A Spit in 2017).
- We use Segment Triggered Campaigns to send messages to users when they enter a segment (e.g. Send a welcome email to users who enter the “Created account” segment, send a voter registration email to users on their 18th birthday)
- We use API Triggered Campaigns to send messages to users within a segment (e.g sending a SMS broadcast to all users who signed up for Mirror Messages). See the Gambit wiki for more details on how SMS broadcasts work.
Environments #
We maintain two separate Customer.io workspaces, one for production and for QA. Because all Customer.io campaigns are manually created within the UI, there is disparity between the Customer.io campaigns (and transactional email messaging) in each environment. For example, we don’t have any Campaign Review Event Triggered Campaigns set up in QA, as we do in production.
Events #
Our internal apps track the following events in Customer.io:
Campaign Signup #
When a user signs up for a campaign, Rogue tracks a campaign_signup
event in Customer.io.
We use Event Triggered Campaigns to send confirmation emails to a user upon signup. Most campaigns use a general Event Triggered Campaign we’ve created, but we’ve also created a handful of Event Triggered Campaigns that filter by the campaign_id
property on a campaign_signup
event, to customize the email content per the campaign.
Gotcha - Our general Campaign Signup Event Triggered Campaign (linked to above) must then exclude each campaign_id
that has a custom Event Triggered Campaign, to avoid sending users two emails upon signup creation if they sign up for one of the campaigns that has its own Event Triggered Campaign for campaign_signup
events.
Campaign Signup Post #
When a user submits a post, Rogue tracks a campaign_signup_post
event in Customer.io.
Photo Post Received #
We’ve set up an Event Triggered Campaign to send a Photo Received confirmation email for every campaign_signup_post
event sent with type photo
and source not equal to sms
(Production).
Text Post Received #
We’ve set up an Event Triggered Campaign to send a Submission Received confirmation email for every campaign_signup_post
event sent with type text
and source not equal to sms
(Production).
Campaign Review #
When a staff member reviews a post, Rogue tracks a campaign_review
event in Customer.io.
Photo Post Approved #
We’ve set up an Event Triggered Campaign to send a Photo Approved email for every campaign_review
event sent with status approved
and type equal to photo
(Production).
Call to Action Email #
Blink provides a POST /v1/events/call-to-action-email
endpoint that tracks a call_to_action_email
event in Customer.io, requiring type
and actionUrl
properties.
We use separate Event Triggered Campaigns in Customer.io to send emails for each type
of call_to_action_email
event we create:
Forgot Password #
When a user submits the Forgot Password form on the web, Northstar creates a call_to_action_email
event with type forgot-password
, passing a valid password reset URL as the actionUrl
to render as a call to action button within the email content.
Customer.io campaigns:
Activate Account - Rock The Vote #
When a new user is created via Rock The Vote (RTV) import, Chompy posts to the Northstar /v2/resets
endpoint with type rock-the-vote-activate-account
.
Customer.io campaigns:
Activate Account - Email subscription #
When a new user is created via Email Subscription import, Chompy posts to the Northstar /v2/resets
endpoint with type per the subscription topic:
community
- Type:
wyd-activate-account
- Customer.io campaigns: QA, Production
- Type:
lifestyle
- Type:
boost-activate-account
- Customer.io campaigns: QA, Production
- Type:
news
- Type:
breakdown-activate-account
- Customer.io campaigns: QA, Production
- Type:
scholarships
- Type:
pays-to-do-good-activate-account
- Customer.io campaigns: QA, Production
- Type:
Password Updated #
When a user changes their password via reset email or profile, Northstar tracks a password_updated
event in Customer.io, which contains a updated-via
string parameter used to specify where the password was updated from. We use this parameter to send different Event Triggered Campaigns accordingly:
Password Updated Confirmation
We’ve set up an Event Triggered Campaign to send an email to the user confirming their password was changed for every password_updated
event sent where the updated-via
value does not contain activate-account
.
Customer.io campaigns:
Account Activated Confirmation
We’ve set up an Event Triggered Campaign to send an email to the user confirming their account has been activated for every password_updated
event sent where the updated-via
value contains activate-account
.
Customer.io campaigns:
Emails #
Customer.io allows emails to be created via Email Layouts, or a Drag And Drop editor.
Email Layouts #
The Event Triggered Campaigns for call_to_action_email
events are configured to send emails using the DS Default Email Layout (Production, QA).
This layout uses HTML we maintain in Github, and copy/paste into the Customer.io UI. Editors or engineers maintain each email content as HTML, and can render a call to action button that links to the actionUrl
passed in the call_to_action_event
.
Some other emails like our Campaign Signup Event Triggered Campaigns use Email Layouts, but don’t use the DS Default Layout yet (it has been newly added for Event Triggered Campaigns on call_to_action_email
events)
Drag And Drop #
Most other emails sent from Customer.io (e.g. Newsletters) use a WYSWIG editor. Editors select an existing Email Workflow that uses the Drag Drop, and copy/paste the content into a new Email Workflow step to create their email.
Advantages
- Easy to set up column-based layout
- Easy to change styles
Disadvantages
- It’s like copy/paste in Word, styles are copied over from the source text as well as the words
- Too easy to alter boilerplate headers and footers that shouldn’t change per individual emails
Gotchas
- When editing workflow steps in a Customer.io campaign, deleting an Email step will remove all the “Sent” data for the workflow step. This is often not desired (we want to know how many of the emails were sent, even if no longer want to send that specific email), so the workaround is to change the Workflow step that we no longer want to send as “Don’t send” – so there will be 2 workflow steps (one for the new email to send, the 2nd for the old email that was sent that no longer sends). Example:
SMS #
Although Customer.io offers a Twilio integration, we send SMS broadcasts by using a webhook Workflow step, to send an API request to Blink. The rationale behind this can be found in our internal Customer.io Twilio integration assessment.