Sending emails with CSML and Sendgrid

Since the very beginning of the internet, sending emails has always been a core feature for all online services. Today, chatbot are no exceptions, they also need to send emails to users.

Today we're going to go through the (short and easy) process of sending an email with CSML and Sendgrid. You may wonder why Sendgrid: they have a free plan which is always good to start with and the service is also very user friendly on the top of being efficient. In my opinion it is one of the best emailing service to send emails on demand.

Setting up the Sendgrid account

First, you'll need to go to sendgrid.com and sign up for a free (or paying plan) account. Then you'll need to verify your email address and the email address the chatbot will send the emails from.

Last step on Sendgrid will be to create an API key. Go to Email API > Integrategration guide, give a name to your API and create an API key.

That's it, your Sendgrid account is all set!

Sending emails from your chatbot

The Sendgrid documentation gives us a curl request that we can easily translate into CSML using the HTTP client class.

Here is the curl request given by Sendgrid:

curl --request POST \
  --url https://api.sendgrid.com/v3/mail/send \
  --header "Authorization: Bearer $SENDGRID_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"personalizations": [{"to": [{"email": "test@example.com"}]}],"from": {"email": "test@example.com"},"subject": "Sending with SendGrid is Fun","content": [{"type": "text/plain", "value": "and easy to do anywhere, even with cURL"}]}'

Here is the CSML equivalent:

do r = HTTP("https://api.sendgrid.com/v3/mail/send")
    .set({"Authorization": "Bearer {{SENDGRID_API_KEY}}"})
    .post({"personalizations": [{"to": [{"email": "test@example.com"}]}],"from": {"email": "test@example.com"},"subject": "Sending with SendGrid is Fun","content": [{"type": "text/plain", "value": "and easy to do anywhere, even with cURL"}]})
    .send()

Let's go through the CSML code together.

First, and as mentioned in the CSML documentation, the url (is given as argument of the HTTP constructor. Then headers are passed in the set() method, here we only set the Authorization as the Content-Type is set by default to application/json in CSML. Last but not least, the data object is set as argument of the post method. Note that we will obviously need to edit this object with a suitable email subject, body, and from/to email addresses.

More informations about the Sendgrid API over here

Chatbot integration

Now that we have the Sendgrid account setup and the CSML code to send the email, let's build a quick chatbot that will ask a few questions to the user and will send an email at the end of the flow.

start:
  remember SENDGRID_API_KEY = "YOUR SENDGRID KEY HERE"
  // The address below must be verified by Sendgrid prior sending the email
  remember SENDER_EMAIL_ADDRESS = "chatbot@example.dev"
  say "Hello 👋 "
  say Typing(2000)
  say "In order to send you awesome contents, I'll just need your name and email address"
  goto getName

getName:
  say Typing(2000)
  say "What's your name?"
  hold
  remember name = event
  goto getEmail

getEmail:
  say Typing(2000)
  say "What's your email address?"
  hold
  if (!event.is_email()) {
    say "This email address is invalid :("
    goto getEmail
  }
  remember email = event
  goto sendEmail

sendEmail:
  say "Ok {{name}}, I've send you an email with a cool content 😎 "
  do r = HTTP("https://api.sendgrid.com/v3/mail/send")
    .set({"Authorization": "Bearer {{SENDGRID_API_KEY}}"})
    .post({
      "personalizations": [{"to": [{"email": email}]}],
      "from": {"email": SENDER_EMAIL_ADDRESS},
      "subject": "Check this awesome content",
      "content": [{
        "type": "text/html", 
        "value": "Here is an awesome photo <br> <img src=\"https://i.pinimg.com/originals/7f/26/e7/7f26e71b2c84e6b16d4f6d3fd8a58bca.png\">"
    }]})
    .send()
  say "Bye!"
  goto end

Note that in development mode that may encounter this error:

failed to read response as JSON at line 38, column 6 at flow [Default]

This is not really an error, since Sendgrid does not send an answer to the HTTP request, CSML raises a warning as the non-existent response cannot be parsed.

If you'd like to test the chatbot and play with it, you can do it on the CSML playground over here 👉 https://play.csml.dev/bot/36a1ab4a-9b5c-44c3-91b7-1848220df5e0