At AMEE, we've been using Sendgrid and KissMetrics to take care of delivering email and understand how our apps are used in more detail for a while now (we'd never be able to deliver the same level of service internally as they can, and they get better for free), but as is often the case when working with disparate third party services, they don't _always_ work together how you want.

One of the reasons we use these two services however, is that they provide a rich enough API to combine them to plug gaps like we mentioned above.

For example, we use Sendgrid for transactional email, and it does a sterling job when it comes to actually making sure email ends up in the right inbox. But if we wanted to see what a user did with an email it had arrived, and log that for analysis later, we could't find a simple way to do this.

Likewise with KissMetrics - it's straightforward enough to create a libary of events in the browser to log, that you can then combine in groups to build reports on how well a certain conversion funnel is performing. But if you want to track things happening outide a user's browser (say, deep in the innards of your own application, or in an hosted email service) you'll need to roll your sleeves up and start monkeying around with the API.

### Keeping you POSTed with Sendgrid

Sendgrid has made a name for itself sending billions and billions of emails, but it doesn't retain accessible logs of the state of every email sent using its service ever, but the API doesn't really let you ask a question like: "what happened to every email sent to joe.bloggs@foo.com ?".

What it _does_ do however, is provide an event API, which can hit a predefined endpoint, to send along updates about the progress of a message being sent to a particular address, as it gets queued for delivery, marked as spam, bounced, delivered successfully, opened, and so on.

Of course, for any of this to work, you actually need somewhere to send these messages to.

### Sending messages to KissMetrics

Fortunately, Kissmetrics has a refreshingly simple API, so setting up a simple Sinatra app, `km-sinatra`, to get the two services running together was relatively painless, once we'd worked out how to get sinatra and rspec playing nicely together.

Here's a high level view of what it looks like:



### What does the code look like though?

The first pass for making the code was as pretty much as simple as this:

  post "/" do
    if params[:category] == "ProjectName"
      # setup connection with KissMetrics, passing in API key, giving us an object, `KM` to work with
      initialise_km

      # identify our user, based on the email address passed along by sendgrid
      KM.identify(params[:email])

      # log the appropriate event for our user
      case params[:event]
        when 'processed'
          KM.record('processed for delivery')
        when 'delivered'
          KM.record('received mail')
        when 'open'
          KM.record('viewed mail')
        when 'click'
          KM.record('clicked link')
        when 'bounce'
          KM.record('bounced mail')
        when 'dropped'
          KM.record('drop mail')
        end
    end
    # give us an ok response with Sinatra
    200
  end