Integrating with Email Service Providers in dashdash

If you’re currently using an Email Service Provider (ESP) for some of your marketing and/or sales communication, there are some very powerful use cases waiting for you when integrating your ESP with dashdash.

Quick download on Email Service Providers (ESPs)

An email service provider (ESP) allows users to send email campaigns to a list of subscribers.
At the most basic level, an ESP needs to do two things: 1) store email addresses and 2) send emails.

Generally, you can differentiate between two types of ESPs:

  • List based ESPs (like Mailchimp, ActiveCampaign, or Emarsys)
  • Transactional ESPs (like Sendgrid or Mailjet)

These two types have different heritages, and to some extent different functionalities.
Many companies are using both—list-based ESPs for marketing (newsletters) and transactional ESPs for communication like password reset emails, order confirmations, etc.
It’s recommended to use both types since your IP reputation might suffer when sending marketing campaigns—and therefore some of your emails might get stuck in the spam folder.

As this really shouldn’t happen to order confirmations for example, there’s usually a split between the two communication streams. (You could also simply split IPs, but I won’t get into detail on this here.) If you’re interested in learning more, check out the blog posts published by the ESPs on deliverability management.

I will use Sendgrid as an example here. It’s a transactional ESP and offers a free self-sign-up; has some nice personalization functionalities; and has a great and well-documented API.

Mailchimp actually differs a little bit from Sendgrid and other ESPs, so I will publish a separate post only covering Mailchimp and link it here once it’s ready.

APIs of list-based ESPs are usually comparable and so are APIs of transactional ESPs.
So once you’ve worked your way through this post, you should be set for almost any API :slightly_smiling_face:

Integrating with Sendgrid

Make sure to have a quick look at Sendgrid’s API documentation beforehand.
I will be using the API V3 and dynamic templates here.

Adding/Updating a contact to a list

Let’s say you sourced some leads with dashdash and want to add them to your marketing list.

Quick reminder—we need 3 parameters for the PUT request:

  1. Action URL
  2. Header
  3. Body

Let’s build each parameter step by step.

First, we will be using the following end point/URL:

PUT https://api.sendgrid.com/v3/marketing/contacts

Now, we’ll need to build the Header:

Sendgrid only requires your API key, so that’s an easy one.

Your Header should look like this:
Authorization: Bearer YOUR API KEY

One way to build the header in dashdash is using the PAIR2JSON function.
Simply type “Authorization” in one cell—A1 for example—and Bearer YOUR API KEY in B1.
In C1 we then turn these two cells into a JSON object by using the function PAIR2JSON(A1,B1) which we’ll include in the POST request later.

Hint: When using the PAIR2JSON function, you don’t need to put “:” after the first argument, the function does this automatically.

Lastly, we can build the actual body/payload.
Make sure to take a quick look at the Sendgrid Docs:

https://sendgrid.api-docs.io/v3.0/contacts/add-or-update-a-contact

Sendgrid only requires two fields for adding contacts to a list:

  • List ID
  • Email

All other fields are optional, yet they might be useful for you.
However, there are two different types of fields:
Standard fields and Custom fields.

For this example, we will be using: Firstname, Lastname, Email, Phone, City, and one custom field: Company.
Your sourced data could look like this:

And this would then be your payload in dashdash, including the list ID you’ll get from Sendgrid:

 ' {
      "list_ids": [
        "5846d3b0-28ad-4007-b0a6-3d940d94a811"
      ],
      "contacts": [
        {
          "city": "'&E5&'",
          "email": "'&C5&'",
          "first_name": "'&A5&'",
          "last_name": "'&B5&'",
          "phone_number": "'&D5&'",
          "custom_fields": {
            "e1_T": "'&F5&'"
          }
        }
      ]
    }
    '

We used one custom field in order to add the company information.
If you decide to use other custom fields, check out the custom field section of the documentation:

https://sendgrid.api-docs.io/v3.0/custom-fields/create-custom-field-definition

Sending an email/triggering a dispatch:

Let’s say you have a nicely formatted pre-built template that you want to send out to leads you sourced in dashdash, or have an onboarding email you want to trigger, this is the way to do it.

This time, we’ll use a POST request, also consisting of 3 components:

  1. Action URL
  2. Header
  3. Body

We will be using the following End Point/URL:

POST https://api.sendgrid.com/v3/mail/send

We can use the same header as we did when adding contacts above.

When building the body/payload, have a look at the Sendgrid documentation—you can actually customize quite a lot.

First, make sure you have your template ready to use.
In my setup, the template looks like this:

As you can see, the template uses some variables as personalization placeholders.
These are only some pretty basic ones and Sendgrid actually allows for quite some personalization including handlebars, so you can build some pretty cool and advanced templates.
In case you’re interested in handlebars, have a look at this:

https://sendgrid.com/docs/for-developers/sending-email/using-handlebars/#handlebars-overview

So, how do we actually build the template and make sure it’s using the right personalization?
Let’s have a quick look at how my data looks like in dashdash:

And the actual payload we are using for the API call:

'{
   "from":{
      "email":"'&B4&'",
     	"name" : "'&B5&'"
   },
   "personalizations":[
      {
         "to":[
            {
               "email":"'&B9&'"
            }
         ],
         "dynamic_template_data":{
            "firstName":"'&B10&'",
           	"supportmail": "'&B11&'"
          }
      }
   ],
   "template_id":"'&B6&'"
}
'

The dynamic template data is the important part here.
If you’re using variables, make sure to use the exact same spelling (case sensitive) in your payload—otherwise, the template will not be populated correctly.

Now you’re ready to trigger your first marketing email from dashdash :mailbox:

5 Likes