Do you have an email list and want it segmented by geographic location? This blog post has got you covered! To accomplish this task, we take advantage of SendGrid’s Event Webhook. If you’re not familiar with what a webhook is you can find out more HERE. But to give a brief intro, webhooks are reverse API calls.

Normally, when your application takes advantage of SendGrid, it tells us through our API to send out a marketing campaign or maybe some type of account notification email. With webhooks, SendGrid now sends YOUR application data.

Event Webhook


This webhook will send your application info when an event occurs with an email you sent out. For example, if a user clicks on a link, we’ll notify your app. There are many more events that we report on. These can be seen in the pic above. For this application we will be taking advantage of the Open event.


Start by cloning this repository:

Then type in the following instructions to get the app setup on heroku (more details on getting setup with heroku):

$ heroku create
$ heroku config:set list="NewList" #This is the new list you created in the SendGrid marketing Dashboard
$ heroku config:set api_user="YourUsername" #SendGrid account username
$ heroku config:set api_key="YourPass" #SendGrid account password

Next, deploy your app and put the url in the Event Notification app settings. Whenever you send out your next campaign, you will notice emails being added to your list associated with their location.

How does it work?

As soon as an email is opened up our app above gets the users IP. From there, we use another API provided by freegeoip and get the users location. The app then appends that email and location to the list you provided.

If you have any questions. You can email me or tweet me @kunal732! Enjoy segmenting!

Meet Kunal, Developer Evangelist at-large for SendGrid and home-grown New Jersey hacker. He previously ran General Machines, which developed Deaftel - a phone service for the deaf that converts voice to text and text back into voice over a phone call. Since March 2013, Kunal has been working as a Developer Evangelist at SendGrid, helping enable developers to get the tools and resources they need to make awesome, creative stuff.