Skip to content

Email handling

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

The mail() function

Each Botsquad 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.

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\">Botsquad</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 Botsquad platform sends all emails via the Mailgun service. You can use your own Mailgun account credentials by creating a mailgun YAML file in the bot, which needs to contain the sending domain, the Mailgun API key and the sender details, like this:

api_key: "key-a7e6d8f6a7f8a6dea8ed68a768f"
domain: "example.com"
from_name: "Uncle Bob"
from_email: bob@example.com

from_name is optional; if you leave it out, the bot's name is used as the sender's name.