Send Emails That Don’t Bite With Barke


Posted on

barke barke

People are different. They read their email at different times and in different ways. But it’s not easy to track and react to different users’ habits. That’s the idea behind Embarke, a partner of ours that optimizes the delivery time of each email you send.

Embarke mimics our Web API and then consumes data provided by our Event Webhook to allow users to continue sending through SendGrid with minimal changes on their end.

To start using Embarke, all one needs to do is change their endpoint from:

https://api.sendgrid.com/api/mail.send.json

to

https://esp.embarkemail.com/sendgrid/api/mail.send.json

and pass in a few extra values through the x-embarkeapi header.

Typically, its fairly easy to switch one of SendGrid’s API Clients to an Embarke client. For example, to send email through Embarke using our PHP Library you only need to do the following:

$embarke = new SendGrid('username', 'password', array( 'url' => 'https://esp.embarkemail.com/sendgrid/api/mail.send.json'));

However, it still feels kind of weird to instantiate a SendGrid library to send email through Embarke. For this reason, and as a fun experiment, I decided to write barke(pronounced “bark-ey”)– a Node.js client library for Embarke based off sendgrid-node.js.

If you like you can start using it today with:

npm install barke

Behind The Scenes

My goal in creating this library was to give the user as native a feel as possible, while not actually modifying the SendGrid module outside of what was immediately exposed.

In the library’s initial version, it simply changed the URL the library used from our endpoint to Embarke’s. However, this still meant you had to pass in everything Embarke needed as a header string.

{
  // ...
  headers : {
    'x-embarkeapi' : '{ "sendDate": "2013-05-26T18:00Z", "maxSendHours": 24, "campaignId": "My Campaign", "mailAccount": "esp-account-username", "tags": ["My custom tag1", "My tag 2"] }'
  }
  // ...
}

Not the greatest experience. So, I endeavored to create a better, more native-feeling experience, perhaps an object: Email.embarfkeapi. Similar to our existing Email.smtpapi this, however, presented a challenge as the email object is instantiated without an embarkeapi parameter and forcing it to be instantiated with one would mean overwriting a function– causing some pretty unsustainable code.

For this reason, barke gets a little hackey. Instead of modifying the email function’s instantiator, it just creates the embarkeapi object lazily when it becomes necessary:

if(typeof this.embarkeapi == "undefined") {
  this.embarkeapi = {};
}

It further modifies the send method so that before finally sending the message, barke puts everything into the right place and formats it correctly for Embarke’s API.

Why?

In creating software, it’s incredibly important to make things easy to use, and great to have things just work. You know you’ve done a good job when developers can start guessing at method names or method behavior– when questions of how to format something aren’t even necessary. As a developer, it’s a wonderful experience to try something that you’re sure won’t work– because it’s too easy, and then succeed. In programming, especially open source, these are the experiences you want to create.


Nick Quinlan is a SendGrid Developer Evangelist based out of San Francisco. He works to make developers lives easier by providing them with the help they need to grow their ideas. Give him a shout, @YayNickQ.

Nick Quinlan on Twitter

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>