Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 121 lines (75 sloc) 5.603 kb
5b3f90d @stephenb Updating the readme to use markdown and polishing it up a bit.
authored
1 sendgrid
2 =========
3
4 _Now updated to work with Rails 3._
5
6 What is SendGrid?
7 -----------------
8
9 SendGrid is an awesome service that helps you send large amounts of email (bells and whistles included) without spending large amounts of money. This gem allows for painless integration between ActionMailer and the SendGrid SMTP API. The current scope of this gem is focused around setting configuration options for outgoing email (essentially, setting categories, filters and the settings that can accompany those filters). SendGrid's service allows for some other cool stuff (such as postback notification of unsubscribes, bounces, etc.), but those features are currently outside the scope of this gem.
10
11 Visit [SendGrid](http://sendgrid.com) to learn more.
12
13 Getting Started
14 ---------------
15
16 First of all, you'll need the gem. It's at http://rubygems.org/gems/sendgrid. If you're using Bundler, just add the following to your Gemfile.
17
18 gem 'sendgrid'
19
20
21 Before you can do anything with the sendgrid gem, you'll need to create your very own SendGrid account. Go ahead and do so at [http://sendgrid.com](http://sendgrid.com) (there's even a FREE account option).
22
23 Next, update your application's SMTP settings to use SendGrid's servers (see [SendGrid's getting started guide](http://wiki.sendgrid.com/doku.php?id=get_started) for instructions).
24
25 Example:
26
27 ActionMailer::Base.smtp_settings = {
28 :address => "smtp.sendgrid.net",
29 :port => 25,
30 :domain => "mysite.com",
31 :authentication => :plain,
32 :user_name => "sendgrd_username@mysite.com",
33 :password => "sendgrid_password"
34 }
35
36 Using the sendgrid Gem
37 ----------------------
38
39 If you do not already have an ActionMailer class up and running, then check out [this guide.](http://guides.rubyonrails.org/action_mailer_basics.html#walkthrough-to-generating-a-mailer)
40
41 1) add the following line within your mailer class:
42
43 include SendGrid
44
45
46 2) customize your sendgrid settings:
47
48 There are 2 main types of settings
49
50 * Category settings
51 * Enable/disable settings
52
53 You can set both global and per-email settings - the same syntax is used in either case.
54 Here is an example of what typical usage may look like:
55
56 class MyMailer < ActionMailer::Base
57 include SendGrid
58 sendgrid_category :use_subject_lines
2c6a37c @stephenb fixing typo in readme
authored
59 sendgrid_enable :ganalytics, :opentrack
5b3f90d @stephenb Updating the readme to use markdown and polishing it up a bit.
authored
60
61 def welcome_message(user)
62 sendgrid_category "Welcome"
63 mail :to => user.email, :subject => "Welcome #{user.name} :-)"
64 end
65
4331623 @stephenb another small typo fix in readme
authored
66 def goodbye_message(user)
5b3f90d @stephenb Updating the readme to use markdown and polishing it up a bit.
authored
67 sendgrid_disable :ganalytics
68 mail :to => user.email, :subject => "Fare thee well :-("
69 end
70 end
71
72 Category settings can be any text you like and SendGrid's website will allow you to view email statistics per-category (very nice). There is also a custom global setting that will automatically use the subject line of each email as the sendgrid\_category:
73
74 sendgrid_category :use_subject_lines
75
76 If you have any dynamic subject lines, you'll want to override this setting within the mailer method. Calling sendgrid\_category from within one of your mailer methods will override this global setting. Similarly, calling sendgrid\_enable/sendgrid\_disable from within a mailer method will add or remove from any defaults that may have been set globally.
77
78 Here are a list of supported options for sendgrid\_enable and sendgrid\_disable:
79
80 * :opentrack
81 * :clicktrack
82 * :ganalytics
83 * :gravatar
84 * :subscriptiontrack
85 * Call sendgrid\_subscriptiontrack\_text(:html => 'Unsubscribe <% Here %>', :plain => 'Unsubscribe Here: <% %>') to set a custom format for html/plain or both.
86 * OR Call sendgrid\_subscriptiontrack\_text(:replace => '|unsubscribe\_link|') to replace all occurrences of |unsubscribe\_link| with the url of the unsubscribe link
87 * :footer
88 * Call sendgrid\_footer\_text(:html => 'My HTML footer rocks!', :plain => 'My plain text footer is so-so.') to set custom footer text for html, plain or both.
89 * :spamcheck
90 * Call sendgrid\_spamcheck\_maxscore(4.5) to set a custom SpamAssassin threshold at which SendGrid drops emails (default value is 5.0).
91
92 For further explanation see [SendGrid's wiki page on filters.](http://wiki.sendgrid.com/doku.php?id=filters)
93
94
95 Delivering to multiple recipients
96 ---------------------------------
97
98 There is a per-mailer-method setting that can be used to deliver campaigns to multiple (many) recipients in a single delivery/SMTP call.
99 It is quite easy to build a robust mass-delivery system utilizing this feature, and it is quite difficult to deliver a large email campaign quickly without this feature.
100 Note: While it may be worth asking yourself, a SendGrid engineer told me it's best to keep the number of recipients to <= 1,000 per delivery.
101
102
103 sendgrid_recipients ["email1@blah.com", "email2@blah.com", "email3@blah.com", ...]
104
105
106 One issue that arises when delivering multiple emails at once is custom content. Luckily, there is also a per-mailer-method setting that can be used to substitute custom content.
107
108
109 sendgrid_substitute "|subme|", ["sub text for 1st recipient", "sub text for 2nd recipient", "sub text for 3rd recipient", ...]
110
111
112 In this example, if <code>|subme|</code> is in the body of your email SendGrid will automatically substitute it for the string corresponding the recipient being delivered to. NOTE: You should ensure that the length of the substitution array is equal to the length of the recipients array.
113
114
115 TODO
116 ----
117
118 * Test coverage (I would appreciate help writing tests).
119 * Possibly integrate with SendGrid's Event API and some of the other goodies they provide.
120
Something went wrong with that request. Please try again.