Connecting Email via Mandrill

Guests still write emails, and your Agent can answer them. You connect your own Mandrill (Mailchimp Transactional) account, tell us which mailbox addresses to watch, and bind one to an Agent as a Channel. From then on, every guest email to that address gets a reply from your Agent, sent from your own domain. This article walks you through the whole setup, start to finish.

Email is a little more involved than our other Channels, because mail has to flow through your own domain. Set aside 30 minutes, and have someone on hand who can edit your DNS records.

How the Pieces Fit Together

There are three levels here, and knowing which is which will save you a lot of guesswork:

• Your Mandrill account holds your inbound domain and its routes. This is where guest email physically arrives. It stays yours, and you set it up in Mailchimp.
• A Connector lives at the Organization level. It holds your Mandrill credentials and the list of mailbox addresses you want to use. You set this up once.
• A Channel lives on an Agent. It binds one of your Connector's mailboxes to that Agent, so the Agent answers on it.

So the path is: get mail arriving at Mandrill, build the Connector once, then hand a mailbox to each Agent that needs one. Different Agents can answer on different mailboxes, all from the same Connector.

What You'll Need

Email runs on Mandrill, and you bring your own account. Mandrill is Mailchimp's transactional email service, and it's the email service we support today. A few things need to be in place before you start:

• A Mandrill account. The account stays yours. We never create or own it.
• A verified inbound domain in Mandrill. Your MX records need to point at Mandrill so guest email arrives there. Mailchimp's own guide to setting up inbound email processing walks through adding the domain and validating the records. Use a domain or subdomain you keep just for this, because Mandrill takes over all mail for it.
• A Mandrill API key. You'll find it in your Mandrill settings.
• The mailbox addresses you want to use. For example, frontdesk@yourhotel.com. These are the addresses guests will write to.
• Someone who can edit DNS. Verifying the domain means adding MX records, so loop in whoever manages your DNS.

Note: Setup has a small chicken-and-egg twist. Mandrill only creates the webhook signing key once you've created the inbound route, and creating that route needs a URL that only exists once you've created the Connector. So you'll create the Connector first with a placeholder, then come back and fix it in Step 3. Follow the steps in order and it works out fine.

Step 1: Add a Mandrill Connector

The Connector is what links us to your Mandrill account, so we can receive guest email and send replies back through it.

1. In the backoffice, open your Organization and go to Connectors.
2. Click New connector and choose Mandrill from the list.
3. Give the Connector a Name you'll recognize later (for example, "Hotel Guest Email").
4. Under Allow this connector to…, leave both Receive inbound data and Send outbound data turned on. The Agent needs the first to read guest email, and the second to reply. Both are on by default, so you can leave this as is.
5. Under Mailbox addresses, click Add Item and enter an address this Connector should handle, like frontdesk@yourhotel.com. Add as many as you need.
6. Enter your API Key.
7. In Webhook Key, type any placeholder for now, such as placeholder. Mandrill hasn't created the real key yet, and you'll replace this in Step 3.
8. Click Create connector.

We test your API key against Mandrill right away. When it checks out, the Connector shows as Active. If the key can't be verified, the Connector is saved in an Error state so you don't lose your setup. Just edit it, re-enter the key, and save again.

Note: Your API key and webhook key are secrets, just like passwords. We store them securely and only use them to reach your Mandrill account.

Step 2: Register the Webhook URL in Mandrill

This is the step that makes incoming email actually reach your Agent. A webhook is a URL Mandrill calls every time an email arrives. Point Mandrill at us, and each guest email lands with your Agent.

1. Open your new Connector's detail page and find the Inbound webhook URL.
2. Click Copy to copy the whole thing. (Reveal shows it on screen first if you'd like to see it.)
3. In Mandrill, go to Inbound and open your inbound domain.
4. Click the dropdown next to Test DNS Settings, choose Routes, then click Add New Route.
5. Enter the mailbox address you want to receive on, paste the copied URL as the webhook, and click Save.

Mailchimp covers this part in configure your incoming email address and webhook, if you'd like their version alongside ours.

The URL looks like https://api.agent.trustyou.com/api/webhook/connector/cn_xxxxxxxx?secret=…. Paste it exactly as we give it to you, including everything after the question mark. That trailing part is what proves the request really came from Mandrill. Drop it or change it, and guest email stops arriving.

Mandrill sends a quick test call when you save the route. We answer it, and your route saves.

Note: If you ever click Regenerate on the webhook URL, the URL changes and you'll need to paste the new one into Mandrill, or incoming email will stop arriving. The same goes the other way: if you use Reset key in Mandrill, come back and update the Connector's Webhook Key to match.

Step 3: Replace the Webhook Key

Don't skip this one. Now that the route exists, Mandrill has created its signing key, and we need it. The Connector page reminds you with a yellow banner until you've done it.

1. In Mandrill, go to Settings and open the Webhooks tab.
2. Find your webhook in the list. Each one is listed by the URL it posts to, so look for the one matching your Connector's Inbound webhook URL. Its description reads "Inbound email for" followed by your mailbox address.
3. Copy the value under Key. Mandrill created it for you, so there's nothing to generate.
4. Back in the backoffice, open the Connector and click Edit.
5. Type the key over what's in Webhook Key, and click Save changes.

If you run several mailboxes, you'll see several webhooks here, each with its own key. Match them up by URL and take the key from the right one, or inbound mail for that mailbox stays blocked.

Until you do this, every guest email gets turned away, because we can't confirm it really came from Mandrill. Worse, Mandrill switches a webhook off after 20 failed attempts in a row, and then you'd have to turn it back on by hand. So finish this step right after Step 2.

Step 4: Add the Channel to Your Agent

With the Connector ready, hand a mailbox to the Agent that should answer on it.

1. Open the Agent you want to connect, and go to Channels.
2. Click Add channel.
3. Pick your Mandrill Connector, then pick the mailbox address you want this Agent to use.
4. Click Add channel to save.

The mailbox now shows on the Agent's Channels page with an Email badge, labeled with the Connector it came from.

To stop an Agent from answering on a mailbox, remove the Channel here. That only unbinds the mailbox from this Agent. Your Connector and its settings stay intact.

Note: Mandrill mailboxes always show a Webhook not set up in provider label here, even once everything is working. Mandrill doesn't let us read your inbound route settings back, so we can't confirm the route from our side. As long as you completed Steps 2 and 3, you can ignore it.

How It Works

Once everything is connected, the flow is simple:

1. A guest emails your mailbox address.
2. Mandrill receives it and forwards it to the Agent bound to that address.
3. The Agent reads the email and replies from the same address.

The reply comes back as a proper reply. The subject line picks up a "Re:" and the right headers go along with it, so the guest sees one tidy thread in their inbox instead of a pile of loose messages.

There's nothing for your team to do in the moment. The Agent handles each email on its own, the same way it does on web chat.

Email Isn't Instant

Mandrill gathers up incoming email and passes it to us in batches, roughly once a minute. So expect at least a minute between a guest hitting send and the reply arriving, sometimes a little more. That's normal for email, and it's worth mentioning to your team so nobody thinks something's broken.

One Mailbox, One Conversation

We keep a Conversation going per Agent, mailbox, and guest email address. So if the same guest writes to two different mailboxes on the same Agent, those are two separate Conversations, each with its own history. Give a guest one address to write to and they'll get one continuous thread.

Good to Know

• Automatic replies get dropped. If an out-of-office responder or another automated system writes in, we spot it and stay quiet, so the two systems can't bounce messages back and forth forever.
• Attachments are ignored, for now. If a guest attaches a file, the Agent reads the message text and skips the attachment. Replies don't carry attachments either.
• Quoted history comes along. When a guest replies and their mail client quotes the whole thread underneath, the Agent sees all of it. Usually harmless, occasionally it makes for a wordier answer.
• Very long emails get shortened. Emails put the newest text at the top, so if one arrives unusually long, we keep the top and trim the rest. The guest's actual question always survives.
• One mailbox, one Agent. Give each mailbox address to a single Agent. If you bind the same address to two Agents, your guests can end up with duplicate replies. One Agent can happily answer on several mailboxes, though, and each of those can carry its own look. See Branding Your Email Replies with a Mandrill Template.

If Email Isn't Arriving

Work through these in order:

1. Check the Webhook Key. A placeholder still sitting in that field is the most common cause. If the yellow banner is still on the Connector page, go back to Step 3.
2. Check the webhook URL in Mandrill. It has to match what we show, character for character, including everything after the question mark.
3. Check Mandrill hasn't switched the webhook off. After 20 failures in a row it disables the webhook, and you'll need to re-enable it in Mandrill.
4. Check the mailbox address matches. The address on the Connector has to be the same address your Mandrill inbound route receives.
5. Check the Channel is bound. Open the Agent's Channels page and confirm the mailbox is listed there.

Don't be thrown by the Webhook not set up in provider label on the Channel. As explained in Step 4, it always shows for Mandrill and isn't a sign of a problem.

What's Next

With email connected, round out your Channels and make sure your Agent is ready for real guests:

• Branding Your Email Replies with a Mandrill Template -- wrap your Agent's replies in your own email design
• Integrating TrustYou Agent Web Chat -- add the Agent to your website as well, so guests can reach you everywhere
• Agent Settings to Review Before Going Live -- run through the pre-launch checklist before your first guest writes in
• How the Agent Works -- see how the Agent reasons through a guest question