How to: Send HTML emails with the Intercom Conversations API 📮

A short tutorial

A common use case for our Conversations API is to send emails — often with HTML formatting — via the API. In this quick tutorial we’ll show you how to send a message using the Conversations API, and which HTML formats can be used.

We’re using the Node SDK for our examples, but you can use any of our SDKs in the same way 👌

First: Messages vs. Conversations endpoints

You might notice that there are two endpoints that you can use to talk to customers: https://api.intercom.io/messages and https://api.intercom.io/conversations

Let’s quickly cover the differences:

• If you’re initiating contact with a new message — for example, sending out an announcement email — then you’ll use the ‘messages’ endpoint.
• Once the initial message is sent and you want to send a reply or take an action on the conversation (like closing it), you’ll use the ‘conversations’ endpoint.

Each part or reply within a conversation is a message, so essentially messages make up conversations.

So, now that we’ve got that covered, let’s get on with sending an email message to a lead.

Sending a message

We’re starting a new conversation, so we need to use the ‘messages’ endpoint. In most cases, you will send messages to customers as an admin.

Here’s the Node code for sending an HTML email message to a lead via the API:

Sending an email to a lead, from an admin

Alternatively, we could have chosen to send this as an in-app message. Which you choose will depend on your own use case, but just be aware of some differences in the POST body for each type — for example, you don’t need a ‘subject’ attribute when sending an in-app message.

What HTML can be used?

We’ve included some basic HTML formats in the example above. Whilst we don’t support the HTML Style attribute, you can include some basic HTML as we’ve shown.

Those include:

• Headers and paragraphs
• Ordered and unordered Lists
• Bold/italics/highlighted/underscored
• Tables
• Images

Here’s what the message example above looks like:

An example of supported HTML

Next time: Retrieving conversations

This should give you a good idea of how to send HTML emails.

Next, you may want to retrieve the messages you’ve sent, for example to see who you sent them to or who’s responded. We’ll cover how to do that in our next post, coming soon!

If there’s anything else you’d like to see or you have any question,s let us know in the comments or tweet us at @intercomdevs 👍

And in the meantime, you can check out our docs to discover many more features of the Conversations API.