Mail for Ruby applications.
- Home page: http://lotusrb.org
- Mailing List: http://lotusrb.org/mailing-list
- API Doc: http://rdoc.info/gems/lotus-mailer
- Bugs/Issues: https://github.com/lotus/mailer/issues
- Support: http://stackoverflow.com/questions/tagged/lotus-ruby
- Chat: https://gitter.im/lotus/chat
Lotus::Mailer supports Ruby (MRI) 2+.
Add this line to your application's Gemfile:
gem 'lotus-mailer'
And then execute:
$ bundle
Or install it yourself as:
$ gem install lotus-mailer
- Templates are searched under
Lotus::Mailer.configuration.root
, set this value according to your app structure (eg."app/templates"
). - A mailer will look for a template with a file name that is composed by its full class name (eg.
"articles/index"
). - A template must have two concatenated extensions: one for the format and one for the engine (eg.
".html.erb"
). - The framework must be loaded before rendering the first time:
Lotus::Mailer.load!
.
A simple mailer looks like this:
require 'lotus/mailer'
class InvoiceMailer
include Lotus::Mailer
end
A mailer with .to
and .from
addresses and mailer delivery:
require 'lotus/mailer'
Lotus::Mailer.configuration do
delivery_method :smtp,
address: "smtp.gmail.com",
port: 587,
domain: "example.com",
user_name: ENV['SMTP_USERNAME'],
password: ENV['SMTP_PASSWORD'],
authentication: "plain",
enable_starttls_auto: true
end.load!
class WelcomeMailer
include Lotus::Mailer
from 'noreply@sender.com'
to 'noreply@recipient.com'
subject 'Welcome'
end
WelcomeMailer.deliver
The set of objects passed in the deliver
call are called locals
and are avaliable inside the mailer and the template.
require 'lotus/mailer'
User = Struct.new(:name, :username)
user = User.new('Luca', 'jodosha')
Lotus::Mailer.load!
class WelcomeMailer
include Lotus::Mailer
from 'noreply@sender.com'
subject 'Welcome'
to :recipient
private
def recipient
user.email
end
end
InvoiceMailer.deliver(user: luca)
The corresponding erb
file:
Hello <%= user.name %>!
All public methods defined in the mailer are accessible from the template:
require 'lotus/mailer'
class WelcomeMailer
include Lotus::Mailer
from 'noreply@sender.com'
to 'noreply@recipient.com'
subject 'Welcome'
def greeting
'Ahoy'
end
end
<h2><%= greeting %></h2>
The template file must be located under the relevant root
and must match the inflected snake case of the mailer class name.
# Given this root
Lotus::Mailer.configuration.root # => #<Pathname:app/templates>
# For InvoiceMailer, it looks for:
# * app/templates/invoice_mailer.html.erb
# * app/templates/invoice_mailer.txt.erb
If we want to specify a different template, we can do:
class InvoiceMailer
include Lotus::Mailer
template 'invoice'
end
# It will look for:
# * app/templates/invoice.html.erb
# * app/templates/invoice.txt.erb
The builtin rendering engine is ERb.
This is the list of the supported engines.
They are listed in order of higher precedence, for a given extension.
For instance, if ERubis is loaded, it will be preferred over ERb to render .erb
templates.
Engine | Extensions |
---|---|
Erubis | erb, rhtml, erubis |
ERb | erb, rhtml |
Redcarpet | markdown, mkd, md |
RDiscount | markdown, mkd, md |
Kramdown | markdown, mkd, md |
Maruku | markdown, mkd, md |
BlueCloth | markdown, mkd, md |
Asciidoctor | ad, adoc, asciidoc |
Builder | builder |
CSV | rcsv |
CoffeeScript | coffee |
WikiCloth | wiki, mediawiki, mw |
Creole | wiki, creole |
Etanni | etn, etanni |
Haml | haml |
Less | less |
Liquid | liquid |
Markaby | mab |
Nokogiri | nokogiri |
Plain | html |
RDoc | rdoc |
Radius | radius |
RedCloth | textile |
Sass | sass |
Scss | scss |
Slim | slim |
String | str |
Yajl | yajl |
Lotus::Mailer can be configured with a DSL that determines its behavior. It supports a few options:
require 'lotus/mailer'
Lotus::Maler.configure do
# Set the root path where to search for templates
# Argument: String, Pathname, #to_pathname, defaults to the current directory
#
root '/path/to/root'
# Set the default charset for emails
# Argument: String, defaults to "UTF-8"
#
default_charset 'iso-8859'
# Set the delivery method
# Argument: Symbol
# Argument: Hash, optional configurations
delivery_method :stmp
Attachments can be added with the following API:
class InvoiceMailer
include Lotus::Mailer
# ...
def prepare
mail.attachments['invoice.pdf'] = '/path/to/invoice.pdf'
# or
mail.attachments['invoice.pdf'] = File.read('/path/to/invoice.pdf')
end
end
The global delivery method is defined through the Lotus::Mailer configuration, as:
Lotus::Mailer.configuration do
delivery_method :smtp
end
Lotus::Mailer.configuration do
delivery_method :smtp, address: "localhost", port: 1025
end
Builtin options are:
- Exim (
:exim
) - Sendmail (
:sendmail
) - SMTP (
:smtp
, for local installations) - SMTP Connection (
:smtp_connection
, viaNet::SMTP
- for remote installations) - Test (
:test
, for testing purposes)
Developers can specify their own custom delivery policy:
require 'lotus/mailer'
class MandrillDeliveryMethod
def initialize(options)
@options = options
end
def deliver!(mail)
# ...
end
end
Lotus::Mailer.configure do
delivery_method MandrillDeliveryMethod,
username: ENV['MANDRILL_USERNAME'],
password: ENV['MANDRILL_API_KEY']
end.load!
The class passed to .delivery_method
must accept an optional set of options
with the constructor (#initialize
) and respond to #deliver!
.
All the email are sent as multipart messages by default.
For a given mailer, the framework looks up for associated text (.txt
) and HTML
(.html
) templates and render them.
InvoiceMailer.deliver # delivers both text and html templates
InvoiceMailer.deliver(format: :txt) # delivers only text template
Please note that they aren't both mandatory, but at least one of them MUST be present.
Lotus::Mailer uses Semantic Versioning 2.0.0
Copyright © 2015 Luca Guidi – Released under MIT License