Customer.io Integration

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
• campaign_signup_post
• campaign_review
• call_to_action_email
• password_updated

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:

• Production
• QA

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:

• Production
• QA

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
• lifestyle
  • Type: boost-activate-account
  • Customer.io campaigns: QA, Production
• news
  • Type: breakdown-activate-account
  • Customer.io campaigns: QA, Production
• scholarships
  • Type: pays-to-do-good-activate-account
  • Customer.io campaigns: QA, Production

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:

• Production
• QA

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:

• Production
• QA

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.