SparkPost.com To Segment.com Integration

SparkPost.com offers a webhook facility to share email delivery and engagement events.

Segment.com accepts tracking events and exposes them to its suite of integrations.

This package feeds SparkPost webhook events into Segment.com.

Prerequisites

This package requires:

• a SparkPost account
• a Segment account
• a place to host a public-facing Node.JS-based HTTP service

How It Works

This package is a SparkPost webhook endpoint - an HTTP service which receives batches of email tracking events from SparkPost. It translates the events it receives into Segment.com tracking events which can then be fed into Segment's various integrations. The Event Mapping section describes how that translation takes place.

Setup

Grab the code:

git clone https://github.com/ewandennis/sparkpost-segment-client.git
cd sparkpost-segment-client
npm install

Edit config/default.json and set segmentAPI.key to a Segment.com write API key. See the Configuration section below for more config details.

Start it up:

npm run prod

You now have a SparkPost webhook endpoint at http://YOUR_HOST:3000/api/v1/events.

Finally, register your endpoint with a webhook on your SparkPost account.

Now, when you send emails through SparkPost, you can track them in Segment. See the Event Mapping section below for details on which events are imported with with what fields.

SparkPost -> Segment Event Mapping

SparkPost events are translated into Segment events with this mapping:

SparkPost Event Type	Segment Event Type	Segment Event Name
delivery	track	Email Delivered
bounce	track	Email Bounced
out_of_band	track	Email Bounced
feedback	track	Email Marked as Spam
open	track	Email Opened
click	track	Email Clicked

In addition to the above, the first time this package receives an event for a new message, it emits an identify event to Segment.

Segment events are populated with SparkPost event fields like this:

Segment Field	SparkPost Field(s)
userId	rcpt_to
traits	rcpt_meta, tags

Configuration

The package's configuration is held in config/*.json and uses the config Node.js module. We use the following config fields:

• app
  • port: TCP port the SparkPost webhook endpoint listens on (numeric)
  • maxJSONPayloadSize: how much JSON can we eat? (using bytes notation)
• logging
  • level: log volume ("debug"|"info"|"warn"|"error")
• segmentAPI
  • key: your Segment project write key (string)
  • opts: Segment Node.js client options
• legacyMode: accept legacy or modern style SparkPost events (boolean)
• sparkPost: internal SparkPost to Segment event mapping info
• sparkPostLegacy: internal SparkPost to Segment event mapping info