Email handling

There are several places in which the bot can send an email message to the user.

The mail() function

Each DialoX bot has the ability to send emails, using the mail() function. This function is kept very simple and is meant for short messages that are supposed to get the user back into the chat conversation.

You can define a mail to address, a subject and a body. For full documentation, see the mail() function reference.

If we detect mis-use of the API, sending mails in a very high volume or spamming, we will disable your account.

The e-mail channel

When the e-mail channel has been set up, email messages sent through the mail() function and all other bot-related notification emails will be transported using the email channel, so the sender will be the public email address that was configured in the channel.

Notification emails

Conversations that are started on the web (using the web widget or the PWA) normally cannot be reached back to by the bot. If the bot wants to send another message after the user has left the web browser, an email will be sent to the user if the user has agreed to this.

When a user is offline, but the bot starts talking to a user of which it knows the email address, it will collect its chat messages and send them into a single email message, showing a button to bring you back into the conversation. The email looks like this:

In order to be able to send messages like this, the bots needs to know the user's email address, stored in the user.email variable, and also have the user's permission.

The variable user.email_push_status needs to have the value "ok" in order for a user to receive these notification emails.

You could ask for this permission like this:

dialog ask_email_permission do
  ask "Is it OK if I reach out to you via email?", expecting: ["Yes", "No"]
  if answer == "Yes" do
    if !user.email do
      invoke ask_email # this is a dialog from the BaseBot
    end
    user.email_push_status = "ok"
    remember user
  end
end

Overriding email labels

By defining a labels YAML file, it is possible to customize the fixed labels that are part of the email. To translate the labels in Dutch, for instance, create a labels file and fill it like this:

email:
  kind_regards: "Met vriendelijke groet,"
  powered_by: 'Gemaakt door <a href="https://www.botsquad.com?r=h">DialoX</a>'
  unsubscribe: "Afmelden"
notification_email:
  subject: "Ik heb een bericht achtergelaten"
  introduction: "Dit heb je gemist:"
  call_to_action: "Open de chat"
message_email:
  call_to_action: "Open de chat"

Using a custom Mailgun account

The DialoX platform sends all emails via the Mailgun service. This implies that the sender name and address are always noreply@botsquad.com. To override this, and use your own sender's name and email domain, you can connect your own Mailgun account instead of the one provided by DialoX.

To do this, first ensure that your bot has a YAML file called integrations in its root directory with the following contents:

- provider: mailgun
  context: bot
  description: Integrate with Mailgun

Now, after clicking publish, an Integrations menu item will show up. Click Integrations, and then Mailgun, now click the blue Configure button and fill in the required credentials, such as your API key, mail domain, and sender name and address.

After clicking Save, DialoX will make a test email request to see if the credentials that were entered are valid.

If you use a US mailgun domain, you can remove the API base URI setting, or set it to https://api.mailgun.net/v3.