Email Touchpoints

We are sending emails using Mandrill.

From the technical side, mandrill.js is the module to use. It exports a single method, send(template, context, recipient, callback).

• template can be an actual mandrill template name, or an internal placeholder name defined within mandrill.js in TEMPLATES.
• context is an object with the variables you want to make available to the template. I'd advise you cram as many easily accessible, useful variables into each method call as you can and document what's available so people can modify the templates without requiring code changes each time.
• recipient is the recipient email, or a { name: ..., email: ... } object. Technically it can be a list, but I don't think we need that right now.
• callback(err, result) is your standard callback thing.

Configuring

When you create a Mandrill account, you can set up API keys. This API key needs to go into your environment as CSOL_MANDRILL_KEY. CSOL_MANDRILL_URL has a default value but can be overridden from the environment.

For testing, you can set DEBUG and CSOL_DISABLE_EMAIL to any values to log instead of talking to the Mandrill API.

Templates

In Mandrill, someone will have to define all the needed templates. They can be named whatever you want and have whatever slug is convenient, and those slugs can be mapped to app-internal template names in mandrill.js through the TEMPLATES constant. Once set, it would be better for the slugs not to change too often to reduce the number of tweaks to TEMPLATES.

Templates must have a valid From Address, From Name, and Subject. These can be sent through the API, but we're not currently doing so. Not having these defined may cause failures.

Variables

Template variables passed to send() in the context argument become available in the template itself as *|name|* or *|NAME|*. So with context { foo: 'hi' }, *|FOO|* in a template will get replaced with 'hi'.

API failures

When logged in to Mandrill, the gear icon in the upper right has an API Logs option. Note that a successful API call can still result in a send error. You gotta dig a bit. It's real dumb.

Further Questions?

Ask Mike (mlarsson on irc).