Bidirectional chat-email gateway with Mailgun and GoDaddy
Introduction
Some organizations have expressed a desire to integrate an email channel into Sendbird Chat, for the following use cases:
- The creation of a bidirectional chat-to-email gateway, where a chat conversation can take place between a user in the Sendbird Chat application and another using an email to send and receive chat messages
- Email notifications, where an email service can send a chat message if a Sendbird user is not using the chat application
The method in this tutorial applies to the integration into Sendbird Chat of any communication channel API. For example, we could add a bidirectional channel with the Twitter API. Similarly, we could add a bidirectional SMS channel using the Nexmo-Vonage SMS API.
In this document, I will show you how to integrate an email channel to Sendbird Chat, and how to create a bidirectional chat-to-email gateway.
Prerequisites
To run this proof of concept, you will need:
- A Sendbird account with the webhook feature activated in your chat application.
- A Mailgun account with a plan allowing you to send and receive emails. We have chosen Mailgun for this POC, but you can replicate this logic for any API-based email provider.
- A domain name that you will configure in your Mailgun account. We will use a domain name from GoDaddy in this POC. You can use these GoDaddy DNS settings instructions to configure DNS parameters as per Mailgun instructions available here. We have chosen GoDaddy for this POC, but you can use any domain name provider.
- A Sendbird chat app with its UI. For this POC example, we use the Sendbird React Chat UIKit, more precisely the ‘composed’ React sample application.
- A web server that will host the backend scripts that integrate Mailgun with the Sendbird Chat application. For this POC, we used a free web hosting service from Alwaysdata. You can use any web hosting service supporting PHP 7.3.11 for the scripts.
Now that you are all set let’s dive into the global architecture of the solution and go over the implementation of three use cases covered in this POC.
The Global Architecture
The global architecture of the solution is in the picture below.
| Item | Description |
| Mail client | Communicates with the mail server to send and receive emails. The web server receives a notification when an email containing a picture on an HTML page is opened. This is how an Email API provider understands an opened email that has been opened. |
| Mail server | A mail server can deliver an email to a mailbox or send an email to another mail server (or, in our case, to an Email API provider). |
| Domain name provider | The email API provider needs a domain to send or receive emails on behalf of the provider user account. |
| Email API provider | Service is used to send or receive emails programmatically. |
| Chat-email gateway | Web server receiving webhooks and sending API calls from/to both Sendbird and the email API provider. |
| Client app with Sendbird Chat | Client Application implementing Sendbird Chat. In this document, we will use webhooks and some endpoints of the Sendbird Chat platform API. |
Use case 1: An email address receives a chat message
| Flow | Description | ||
| 1 | A new message sent on a Sendbird Chat channel is transmitted via webhooks to the Chat Email gateway | ||
| 2 | If a member of the chat channel is not online in the chat application, the content of the message will be sent to the email API provider to be delivered as an email. | ||
| 3 | The email API provider will use a specific domain name (configured by the account owner) as the domain of the email sender address. | ||
| 4 | The offline Sendbird user will send the email to the Mail server. |
For this use case, we will first configure a Sendbird webhook to redirect the events group_channel:message_send through a script (webhook-sendbird.php) hosted in the Chat Email Gateway, as the configuration documented in the picture below.
Then, we will install and use the Mailgun PHP SDK for the script that will send the received chat message as an email. The payload description of the received chat message is available here. This use case applies to send Email notifications too.
Let’s have a look at this script, named webhook-sendbird.php.
Use case 2. An email is sent to a chat channel
| Flow | Description | |
| 1 | An email is sent from the Mail Server toward an email address that uses the domain name configured in the prerequisite. | |
| 2 | The email is received by the Email API provider. | |
| 3 | A webhook configured in the Email API provider will notify the Chat Email Gateway of this email. | |
| 4 | Using the Sendbird Chat Platform API, the Chat Email gateway will send the related message(s) to the corresponding chat channel. |
We first configure a Mailgun receiving route to forward the inbound email to the Chat Email Gateway backend for this use case. Here’s the related documentation to perform this configuration. We have simply redirected all inbound emails to the endpoint (script inbound-email.php) for this POC, as per the configuration documented in the picture below.
The logic of this script is quite simple. First, we will deduct the chat channel URL to send the related messages from the recipient’s email address. We will forward any email as a text message to the related chat channel and all the files attached to the received email. The payload description of the received email is available here (chapter ‘Parsed Messages Parameters’). The chat platform API endpoint documentation used to send messages to a chat channel is available here. Let’s have a look at this script, named inbound-email.php.
Use case 3. Email events replication toward a chat channel
For a better user experience, it is possible to reproduce email events in a chat channel. Let provide a dynamic update of the following event from the email channel in the chat channel.
| Email event | Related chat event | |
| Email is delivered | The chat message is delivered | |
| Email is opened | The chat message is read |
Let’s review each of the use cases in more detail.
An email is delivered
| Flow | Description | |
| 1 | The mail server confirms the reception of the email to the email API provider. | |
| 2 | A webhook from the email API provider notifies the delivery of an email to the chat email gateway. | |
| 3 | The chat email gateway sends an API Call to the Sendbird platform to update the status of the chat message in delivery. |
An email is opened
| Flow | Description | |
| 1 | The mail client triggers an event to the email API provider that a specific email was opened. | |
| 2 | A webhook from the email API provider notifies the chat Email gateway that a specific email was opened. | |
| 3 | The chat email gateway sends an API Call to the Sendbird platform to update the status of the chat message to read. |
For both events, we will use a similar workflow. The first step is to configure the webhooks of the email API provider for the event delivered and opened. We want the same endpoint to receive both events. When the configuration is complete, a webhook for each event will display in your dashboard. See the picture below.
Each webhook will send the event to the same script (called webhook-mailgun.php). We will use the event documented in the webhook payload to check if this is about a delivered or opened email. The tag in the event will let us know to which chat channel this event relates. Let’s have a look at this script, named webhook-email.php.
Conclusion
In this guide, we’ve covered how to integrate an email channel into a Sendbird Chat application. This approach can ease the transition of your email-based business communication towards chat for a more engaging experience. If you already have one, you can use your current API-based email provider for this integration. We hope you’ll find it applicable to your own business use case. Be sure to reach out and post questions on Sendbird Community if you get stuck.
