I recently had to convert a Rails application that I work
with from Mandrill to SendGrid. The application
was fully functional and live in production.
All of the messages sent by the system were using templates.
The steps that I took included:
1)
Create a new account at SendGrid
2)
Go to Templates -> Transactional and Create
Template
3)
I then cut and pasted each template from
Mandrill to SendGrid
a.
Mandrill was using *|variable_name|* syntax for
replacement variables and I was able to make this work with SendGrid as well.
4)
The one quirk about SendGrid that is worth
mentioning is that I had to add a <%body%> tag to each message even
though I don’t have a payload for <%body%>. I found that the easiest way
to deal with that was to delete it out, switch to code mode, paste in my
complete html and then paste the <%body%> tag as the last thing in my template. SendGrid then did some minor formatting but
left it out of my way.
5)
Each template gets an ID shown at the top of its
information on the Transactional Template Engine page in SendGrid. They look
like: 45ef9876-4321-1cd1-ab1c-d12a123a1234
6)
Go to Settings, API Keys.
a.
Click “Create API Key”.
b.
Save the giant key string that they display.
This is important because they really won’t ever show it to you again.
c.
Edit details for the key you just created and
set security for the functionality you want that key to be able to access. In my case I just set Mail Send = full
access.
7)
Over on the Rails side I create a new class for
SendGrid. Fortunately I had isolate the
email send functionality in my application to one routine so I only had to
create a new sendtemplate method.
8)
I used the sendgrid-ruby gem that is officially supported
by SendGrid. Available here: https://github.com/sendgrid/sendgrid-ruby
Here is the entire file with comments added. In general the
documentation from the gem was very clear and I had only one minor problem
leveraging the API which I’ve referenced in line.
# Begin Code
module RDSendGrid
# I use this to return a
standard result from the class no matter what I get back from the vendor
class FakeRes
attr_accessor :code
attr_accessor :body
end
class RDSendGrid
require "uri"
require 'sendgrid-ruby'
def initialize
end # initialize
##########################################################################
# audit_id: the id of my
internal record for this email
# template_id: the template
id provided by SendGrid for the template I want to send
# from_email: the address to
use as the sender’s email
# from_name: name to show instead of the address in the
recipient’s mail client
# to_email: The address to
send the message to
# to_name: The name of the
person to send the message to
# subject: the subject of the
email message
# merge_vars: an array of attribute
value pairs of replacement variables
# these get sent en-mas to the template engine and are specific to each template
#
the pairs are “name” and “content”
# bcc: provide an email
address here if I want to bcc someone on this message
##########################################################################
def sendtemplate(audit_id,
template_id, from_email, from_name, to_email, to_name, subject, merge_vars, bcc
="")
# defined in my environment
sendgridkey = Rails.configuration.sendgridkey
# This flag allows me to do
email testing without pushing the message to SendGrid
if Rails.configuration. sendmail
# This was the only part that wasn’t crystal
clear to me in the gem documentation
# See my note at the end
# Create an SMTPAPI
header and put settings into it
header =
Smtpapi::Header.new
header.add_unique_arg("rd_audit_number", audit_id)
# Create a SendGrid
recipient to add to the list
# At this time my
sendtemplate function only sends a single message but SendGrid can
# process a list of
recipients so I’ve allowed for that expansion in the future
# Create a sendgid
recipient list
recipients = []
recipient =
SendGrid::Recipient.new(to_email)
merge_vars.each do |mv|
# note that I used *||*
as variable delimiters because they were that way in mandril
recipient.add_substitution('*|' + mv["name"] + '|*',
mv["content"])
end
# Put our one and only
recipient into the array of recpients
recipients <<
recipient
# Create a sendgrid
template
puts(template_id)
template =
SendGrid::Template.new(template_id)
# Create a client
# Note that because I don’t have a body to send I’ve made html and text blank
# However, an empty
string wouldn’t work for me so I used one space
# Adding the smtpapi
header here, this was the second half of the unclear part for me
client =
SendGrid::Client.new(api_key:
sendgridkey)
mail_defaults = {
smtpapi: header,
from: from_email,
from_name: from_name,
to: to_email,
to_name: to_name,
bcc: bcc,
html: ' ',
text: ' ',
subject: subject
}
# Create a new
TemplateMailer
mailer =
SendGrid::TemplateMailer.new(client, template, recipients)
# send it
lres =
mailer.mail(mail_defaults)
# return the result
res = FakeRes.new
res.code = lres.code
res.body =
lres.body["message"]
else
#
Rails.configuration.sendmail was set to false so fake a success return
res = FakeRes.new
res.code =
"200"
res.body =
"success"
end
return res
end #sendtemplate
end
end
# End code
Now about my notes on the SMTPAPI Header. In order to get email events
back from SendGrid, and update my email history with the data, I needed to send
a unique ID for each message to them. The documentation is actually quite clear
on how to do that and how to create an api header for that purpose. The only
thing that was unclear (to me personally) was how exactly to associate that
header with the TemplateMailer call. In the end, it was just a question of
creating the header -- header = Smtpapi::Header.new --, populating it -- header.add_unique_arg("rd_audit_number",
audit_id) -- and then assigning the header to the mail_deafulats -- mail_defaults
= { smtpapi: header … --
So, once again I’ve managed to do something that thousands
have done before me and yet find the need to share it with others anyway. Next time I’ll share how I processed the mail
event updates from SendGrid.
