Introduction

Mandrill is a scalable and affordable email infrastructure service, with all the marketing-friendly analytics tools needed to run successful marketing campaigns. Uluro has integrated the functionality that comes with Mandrill into the Campaign Manager to offer real-time analytics by providing Mandrill with a web hook target that stores the Mandrill events.

This article will help you set Mandrill to supply these analytics and more.

 

****Please note you must have the following programs before you can utilize Mandrill; Web version 3.2.1.7 or later, Usetup version 6.1.1.30 or later, and PDFEmail version 6.1.3.3****

 

Getting Started

Setting up Mandrill

The initial setup of a Mandrill account is simple and straight forward.

1. Open your web browser and navigate to www.mandrill.com.
2. Click the Sign Up button.
3. During the sign up, supply a payment method. The first 12,000 sends are free per month.
4. Select Settings from the dashboard.
5. Select New API Key from to create a key. This will be your main account key.
6. Select Webhooks from the menu on the top of the page.
7. Select Add a Webhook.
8. Select the trigger on events desired for reporting.
9. Enter the Post to URL value. This will be the URL that the webhook sends data to. This will be <Root>/trackingcallback/mandrillcallback.aspx where <Root> is the valid URL for a customer. Example: http://www.myutilitycustomer.com/trackingcallback/mandrillcallback.aspx. This will process all events for all customers of the PSP. Only one is required. Duplicates to the same web application will result in duplicate records!
10. Enter a description for the webhook and save your entry.
11. If this is the main key you will be using, set the Email Tracking Api and Web Hook Key in Global settings\Email Tracking in uSetup 

    If this is for a particular client set the Tracking API key and Web Hook Key in the uSetup Customer Email Settings\Tracking page                             

    See “Mandrill Email Tracking User Document.docx” for more information.

12. Install the uEmailTracking windows service and modify the uEmailTracking.exe.config file with the following:
1. RemotePrint connection string. This will point to the Uluro Database.
2. UluroCPMDB connection string. This will point to the Uluro Web database.
3. MandrillUserName app setting. This will be the valid email address that was used during the Mandrill setup.
4. MandrillKey app setting. This will be the value that was obtained in step 5.
5. MandrillTrackOpen app setting. Either Y or N depending if email open tracking is desired.
6. MandrillTrackClicks app setting. Either Y or N depending if email click tracking in the body of an email is desired.
7. CheckEvery app setting. This will be a whole number between 1 and 65556. This is the number of minutes between processing attempts. It is defaulted to 10.
13. Save and close this file.
14. Open the computer manager.
15. Navigate to the services window.
16. Find uEmailTracking and ensure it is set to run automatically.
17. Select start to begin the service.

Mandrill Trigger Events

The following are trigger events from Mandrill:

1. Sent – This is supplied whenever an email is sent from Mandrill.
2. Deferral – This is sent when an email has been deferred for Mandrill processing at a later time.
3. Hard Bounce - A hard bounce is an e-mail message that has been returned to the sender because the recipient's address is invalid. A hard bounce might occur because the domain name doesn't exist or because the recipient is unknown.
4. Soft Bounce - When e-mailing, soft bounce is used to describe an e-mail that has bounced back to the sender undelivered after it has already been accepted by the recipient's mail server.
5. Open – This is sent when the Mandrill system detects that an email has been opened by a recipient.
6. Click – this is sent when a link in the body of the email has been clicked.
7. Spam – this is sent when a user reports the email as spam.
8. Reject - Recipient email addresses are added to the Rejection Blacklist when one of the following events occurs:
   1. The recipient address bounces,
   2. The recipient address registers a spam complaint for an email sent to that address through the Mandrill account,
   3. The recipient address registers an unsubscribe for an email sent to that address through the Mandrill account, or
   4. The recipient address is manually added to the rejection blacklist.

              Mandrill will not attempt to deliver the emails.

1. Blacklist – An email address has been added to a Rejection Blacklist.
2. Whitelist - Mandrill allows you to whitelist an email address to prevent it from being added to the Rejection Blacklist when a bounce occurs. This can be useful if you're troubleshooting delivery to an internal address that's experiencing issues accepting mail and you want to ensure future messages are attempted even if a previous message bounced, for example. While an address is on the Rejection Whitelist, bounces, unsubscribes, and spam complaints will still be tracked and factored in to your account's reputation, but the address won't be added to the Rejection Blacklist. Mandrill will continue to deliver messages to the address as long as it's whitelisted.

Updating Mandrill Settings

If for any reason it becomes necessary to change the values of the Mandrill Process, stop the UEmailTracking service and follow the directions in the Initial Setup. The Mandrill key can be changed by going to the mandrillapp.com site, logging in and selecting Settings/SMTP & API Info. Then select Delete the API key and generate a new one. Make sure that you follow the instructions in 11 through 17 of the Initial Setup instructions. 

Where to find error messages

Unforeseen errors occur in any system. Errors for this system can be found in the ExceptionErrors table in the web database.

 

Account

Account Details

 

The account details page lists the current balance on the user’s account, as well as numerous stats that are useful in determining the health of the account. In particular, one should examine the “Account Balance”, “Sending Stats” and “Reputation” sections, as all three of these contain details which may relate to issues with sending emails. For instance, if the account is over the hourly or monthly sending threshold, out of money, or has too frequently been marked as spam, it may lose the ability to send.

 

Account Security

 

In some circumstances, clients may wish to opt for a little more security for accessing their Mandrill account. This can be accomplished on the “Account Security” page under the Account tab. In particular, they may wish to configure things so that only certain IP addresses are allowed to work with Mandrill via the API and the website. The app itself currently does NOT support two factor authentication/authorization.

Account Alerts

 

The “account alerts” section allows one to configure email alerts for various events that occur during the processing of emails in Mandrill’s system. It is STRONGLY advised to configure these alerts to be on and to go to an attended mailbox, as they have revenue and system stability implications. The lower section of the screen shows alerts that have been sent from the system.

Outbound Activity

 

The “outbound” activity dashboard is perhaps one of the most important in the mandrill application (at least for our use cases), as it shows graphically the volume of emails sent out, along with click-through and bounce rates over time. This screen is useful for general troubleshooting of outgoing mail issues. Also, it’s important to note the “Show All Options” to the right above the graphs. These can help troubleshoot a little more easily when you have a little more detail about the problem in question.

Reports – Url Tracking

 

The “URL Tracking” section under “Reports” provides a breakdown of URLs being clicked in emails over a date range. This section is useful when something isn’t getting click-throughs and you need to troubleshoot why. For instance, an external company isn’t getting any click-throughs in email messages, but the emails were sent, you can use this section to quickly see if perhaps the target URL is incorrect.

Settings

API Logs

 

The “API Logs” section under “Settings” is useful for seeing the results of calls from our system into Mandrill (in other words, for sending emails). While the image above shows the last few failed calls, the “API Logs” section also has an area for successful calls. Also interesting in this section is the ability to view the time a particular call took to complete, which may be important when troubleshooting performance issues for outbound emails.

Custom Metadata

 

The “Custom Metadata” section under “Settings” allows one to view the custom metadata that is attached to emails going through Mandrill’s system. This area is of somewhat limited utility, but if it doesn’t look like the above image, it can indicate that the system is failing to send along some of the metadata required in order for it to process emails effectively.

Rejection List

Blacklist

 

The “Rejection Blacklist” section under “Settings->Rejection Lists” shows the email addresses to which Mandrill will no longer send messages and the reason for the address(es) being in that list. This can be useful when troubleshooting delivery of messages to particular addresses.

Whitelist

 

It’s worth mentioning here that there is also a “Whitelist” option under “Settings->Rejection Lists” that allows you to enter a list of email addresses that can never be black-listed. Caution is strongly advised insofar as putting anything on this list, as it keeps people from being able to opt-out and could easily cause a violation of CAN-SPAM if misused. However, if someone is having difficulty in opting out, this is probably the first place you should look.

Sending Defaults

 

The “Sending Defaults” section under “Settings” is used for setting up tracking. It is important to make sure that “Track Opens” is checked, or Mandrill will not track the opening of emails (our system still will do so, however). It’s also CRITICAL to make sure that “Add Unsubscribe Footer” is checked in order to avoid violating CAN-SPAM.

Sending Domains

 

The “Sending Domains” (called simply “Domains” in the header for added consternation and confusion) section under “Settings” shows the domains for which emails are currently sent in the system. This is where you would configure DKIM and SPF, as well as verifying domains being used. The settings in this section greatly impact message deliverability. It is recommended that you verify the domain (which will require an email address on the domain), and configure DKIM and SPF for best results.

SMTP & API Info

 

The “SMTP & API Info” section under “Settings” shows the SMTP configuration for this account along with the API keys. Double check the API key used by the sending service if you are receiving errors regarding authentication while attempting to send emails. Also, it’s important to protect these keys, as they are essentially passwords (hence the redaction above). Be sure and also check the permissions assigned to the API keys by clicking “Edit”, to make sure that a key has sufficient permissions to be useful.

Webhooks

 

Webhooks are the endpoints in our system to which Mandrill will send updates. Therefore, it’s critical that they be configured properly. In the “Webhooks” section under “Settings”, one can configure one or more endpoints for Mandrill to call into when something updates. Be sure when creating a webhook for Uluro and related products that the endpoint is configured to receive “send”, “deferral”, “hard_bounce”, “soft_bounce”, “open”, “click”, “spam”, “unsub”, “reject”, “blacklist”, and “whitelist” messages, or inconsistent behavior may occur within the system.

Also, be advised that the area near “Description” will show errors that have occurred on the webhook, and should be checked first if it is suspected that not all mandrill updates are making it through.

Some Further Notes

CAN-SPAM Act

The CAN-SPAM Act, a law that sets the rules for commercial email, establishes requirements for commercial messages, gives recipients the right to have you stop emailing them, and spells out tough penalties for violations. Penalties are stiff.  Each separate email in violation of the CAN-SPAM Act is subject to penalties of up to $16,000. While these regulations are aimed at the sender of the correspondence, Uluro can be crafted to provide automation to the process.

Among the regulations sited in this act, there are a few that can benefit from automation. These are:

• Tell recipients how to opt out of the receiving future email messages. Your message must include a clear and conspicuous explanation of how the recipient can opt out of getting email from you in the future. Craft the notice in a way that’s easy for an ordinary person to recognize, read, and understand. Creative use of type size, color, and location can improve clarity. Give a return email address or another easy Internet-based way to allow people to communicate their choice to you. You may create a menu to allow a recipient to opt out of certain types of messages, but you must include the option to stop all commercial messages from you. Make sure your spam filter doesn’t block these opt-out requests.
• Honor opt out requests promptly. Any opt-out mechanism you offer must be able to process opt-out requests for at least 30 days after you send your message. You must honor a recipient’s opt-out request within 10 business days. You can’t charge a fee, require the recipient to give you any personally identifying information beyond an email address, or make the recipient take any step other than sending a reply email or visiting a single page on an Internet website as a condition for honoring an opt-out request. Once people have told you they don’t want to receive more messages from you, you can’t sell or transfer their email addresses, even in the form of a mailing list. The only exception is that you may transfer the addresses to a company you’ve hired to help you comply with the CAN-SPAM Act.