Using Mandrill Email API

I was working on a hackathon project last weekend, and we need a quick way to send emails out from our Sinatra application. At first we tried to integrate the gmail gem, but after realizing that is an easy way to get that account flagged at spam, we decided to turn to Mandrill by Mailchimp.

I'll show you how to:

• Integrate the Mandrill API
• How to send mail with the Mandrill API
• (COMING SOON)and some quick advanced features in the mandrill API
• How to send with multiple users in To and other fields
• How to suppress users from the To field
• How to use the Mandrill Test Key to make the email call but not actually push out an email to count against your monthly API call limit.
• How to use "Merge Fields" in Mandrill to merge in custom URL's and data into the email about the user you are sending to.

---

Example APP: My Mail Sender

We are going to build a quick application to send email to yourself.

I created a bare bones Sinatra app for this tutorial that you can fork from this repo and clone down.

But first, let's get a Mandrill account.

Get API Key:

Go to [https://mandrill.com/signup/](https://mandrill.com/signup/) and *set up a quick FREE acount*. You just got 12,000 emails per month!

After you create an account, Login.

(Take note of your login info somewhere.)

---

Open up this link: Most useful page for getting started with the Ruby Gem. This was a good basic look at the Mandrill API send email function with the gem 'madrill-api' which will go in your gem file.

STEP 1: add gem 'madrill-api' in your Gemfile as well as gem 'thin'

source 'https://rubygems.org'

gem 'sinatra'
gem 'sinatra-contrib'
gem 'thin'
gem 'mandrill-api'

STEP 2: run $ bundle install

STEP 3: run $ touch .env to create a .env file.

STEP 4: Go to https://mandrillapp.com/settings/index -> the "SMTP & API Credentials" page. Create a new API key.

Add the following to your .env file:

MANDRILL_APIKEY = 'xxxxxxxxxxxxxxxxxxxxx' #test or the #real one

As this getting going page says: The gem assumes your API key is stored as an environment variable called MANDRILL_APIKEY..

So it goes in the .env file and requires no setup beyond that.

STEP 5: add a new folder called lib/ with $ mkdir lib

STEP 6: add a new file in there called lib/email.rb

STEP 7: make a basic ruby class called class MyEmailer in email.rb and also add the 'requires' statements that match the Gemfile at the top. We will also add an empty MyEmailer#send method to the new class.

-------STRANGE THING TO NOTE HERE: The gem is gem 'madrill-api' and the require is require 'mandrill'. Not the same. Confusing.

email.rb at this point:

require 'rubygems'
require 'bundler/setup'
require 'thin'
require 'mandrill'

class MyEmailer
  def send
  end
end

Also add the Mandrill require line to your main Sinatra file: mandrill-tutorial.rb:

require 'rubygems'
require 'bundler/setup'
require 'sinatra'
require 'sinatra/reloader'
require 'thin'				  ## ALSO THIS FOR FOREMAN
require 'mandrill'           ## ADD THIS LINE HERE


get '/' do
  'Welcome to your Mail Sender app!'
end

STEP 7: Run $ bundle install.

STEP 8: Add this code to your MyEmailer#send method:

require 'rubygems'
require 'bundler/setup'
require 'mandrill'

class MyEmailer
  def send(email)
  	
    m = Mandrill::API.new
    message = {  
     :subject=> "Hello from the Mandrill API",  
     :from_name=> "Your name",  
     :text=>"Hi message, how are you?",  
     :to=>[  
       {  
         :email=> "#{email}",  ## this uses the email argument passed into this method
         :name=> "Recipient1"  
       }  
     ],  
     :html=>"<h1>Hi <strong>message</strong>, how are you?</h1>",  
     :from_email=>"[email protected]"  
    }  
    sending = m.messages.send message  
    puts sending
    
  end
end

STEP 9: Go back to the main Sinatra file mandrill-tutorial.rb:

require 'rubygems'
require 'bundler/setup'
require 'sinatra'
require 'sinatra/reloader'
require 'mandrill'

require_relative 'lib/email'  ## THIS IS A NEW LINE AT THIS POINT

get '/' do
  'Welcome to your Penpal app!'
end


get '/send/:email' do
  m = MyEmailer.new
  m.send(params[:email])
  "Email Sent"           ## Sinatra likes to print something out .. so this
end

This will allow you to put in an email address in your browser URI like http://localhost:4567/send/something%40domain.com, and this will send your email into the #send method using GET params.

STEP 10: Run foreman webserver to get going:

$ foreman run ruby mandrill-tutorial.rb

STEP 11: Go visit your neat new homepage:

http://localhost:4567/

STEP 12: Go send yourself an email:

http://localhost:4567/email/youremailprefix%40something.com

NOTE: Fill in your email for: youremailprefix%40something.com in the above URL. Also, %40 is @ in URL encoding.

FINAL: If you go to the branch in the repo you forked above called $ git checkout final;. This is my finished code from this tutorial, so you can check that it is all there compared to your work.

---

Extensions to come:

• How to put in multiple recipients
• How to put in merge fields for those recipients
• How to suppress recipients so they don't all show in the To field.

---

Resources:

Mandrill: Full Message Calls Documentation - for full message calls like adding a more people to the TO field, suppressing recipients, etc.

Where to view API Logs

NOTE: I used FOREMAN by heroku instead of thin or webbrick webserver to get env files to work

---