rubygems

Mail for Ruby applications https://github.com/hanami/mailer

Go to file

Luca Guidi bb063c2862 Don't upload coverage		2022-02-02 11:07:29 +01:00
.github/workflows	Don't upload coverage	2022-02-02 11:07:29 +01:00
bin	Rubocop Hanami dry-rb rules (1.3) (#86 )	2020-10-18 08:40:12 +02:00
config	Remove global state. Immutable mailer. (#69 )	2017-11-29 12:15:12 +01:00
examples	Enforce rubocop rules for 2.0	2017-11-29 12:17:06 +01:00
lib/hanami	Merge branch 'develop' into unstable	2021-01-14 15:24:53 +01:00
script	Don't upload coverage	2022-02-02 11:07:29 +01:00
spec	Ruby 3.0+. Rubocop ~> 1.0. Schedule GitHub Actions. Notify Slack in case of failure.	2022-02-02 09:57:09 +01:00
.gitignore	Merge branch 'develop' into unstable	2017-11-29 11:17:06 +01:00
.jrubyrc	Code quality tools (#74 )	2018-07-24 12:03:38 +02:00
.rspec	Migrate from Minitest to RSpec (#67 )	2017-03-23 16:25:40 +01:00
.rubocop.yml	Updated git branch references	2021-06-15 12:44:30 +02:00
CHANGELOG.md	Merge branch 'develop' into unstable	2021-01-14 15:24:53 +01:00
Gemfile	Updated git branch references	2021-06-15 12:44:30 +02:00
LICENSE.md	GitHub Actions	2021-01-14 12:43:52 +01:00
README.md	Ruby 3.0+. Rubocop ~> 1.0. Schedule GitHub Actions. Notify Slack in case of failure.	2022-02-02 09:57:09 +01:00
Rakefile	Code quality tools (#74 )	2018-07-24 12:03:38 +02:00
benchmark.rb	Merge branch 'develop' into unstable	2020-10-19 09:40:38 +02:00
hanami-mailer.gemspec	Ruby 3.0+. Rubocop ~> 1.0. Schedule GitHub Actions. Notify Slack in case of failure.	2022-02-02 09:57:09 +01:00

README.md

Hanami::Mailer

Mail for Ruby applications.

Version

This branch contains the code for hanami-mailer 2.x.

Status

Contact

Home page: http://hanamirb.org
Mailing List: http://hanamirb.org/mailing-list
API Doc: http://rdoc.info/gems/hanami-mailer
Bugs/Issues: https://github.com/hanami/mailer/issues
Support: http://stackoverflow.com/questions/tagged/hanami
Chat: http://chat.hanamirb.org

Rubies

Hanami::Mailer supports Ruby (MRI) 3.0+

Installation

Add this line to your application's Gemfile:

gem 'hanami-mailer'

And then execute:

$ bundle

Or install it yourself as:

$ gem install hanami-mailer

Usage

Conventions

Templates are searched under Hanami::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: Hanami::Mailer.finalize(configuration).

Mailers

A simple mailer looks like this:

require 'hanami/mailer'
require 'ostruct'

# Create two files: `invoice.html.erb` and `invoice.txt.erb`

configuration = Hanami::Mailer::Configuration.new do |config|
  config.delivery_method = :test
end

class Invoice < Hanami::Mailer
  from "noreply@example.com"
  to ->(locals) { locals.fetch(:user).email }
end

configuration = Hanami::Mailer.finalize(configuration)

invoice = OpenStruct.new(number: 23)
mailer  = InvoiceMailer.new(configuration: configuration)
mail    = mailer.deliver(invoice: invoice)

mail
  # => #<Mail::Message:70303354246540, Multipart: true, Headers: <Date: Wed, 22 Mar 2017 11:48:57 +0100>, <From: noreply@example.com>, <To: user@example.com>, <Cc: >, <Bcc: >, <Message-ID: <58d25699e47f9_b4e13ff0c503e4f4632e6@escher.mail>>, <Subject: >, <Mime-Version: 1.0>, <Content-Type: multipart/alternative; boundary=--==_mimepart_58d25699e42d2_b4e13ff0c503e4f463186>, <Content-Transfer-Encoding: 7bit>>

mail.to_s
  # =>
  # From: noreply@example.com
  # To: user@example.com
  # Message-ID: <58d25699e47f9_b4e13ff0c503e4f4632e6@escher.mail>
  # Subject:
  # Mime-Version: 1.0
  # Content-Type: multipart/alternative;
  #  boundary="--==_mimepart_58d25699e42d2_b4e13ff0c503e4f463186";
  #  charset=UTF-8
  # Content-Transfer-Encoding: 7bit
  #
  #
  # ----==_mimepart_58d25699e42d2_b4e13ff0c503e4f463186
  # Content-Type: text/plain;
  #  charset=UTF-8
  # Content-Transfer-Encoding: 7bit
  #
  # Invoice #23
  #
  # ----==_mimepart_58d25699e42d2_b4e13ff0c503e4f463186
  # Content-Type: text/html;
  #  charset=UTF-8
  # Content-Transfer-Encoding: 7bit
  #
  # <html>
  #   <body>
  #     <h1>Invoice template</h1>
  #   </body>
  # </html>
  #
  # ----==_mimepart_58d25699e42d2_b4e13ff0c503e4f463186--

A mailer with .to and .from addresses and mailer delivery:

require 'hanami/mailer'

configuration = Hanami::Mailer::Configuration.new do |config|
  config.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

class WelcomeMailer < Hanami::Mailer
  return_path 'bounce@sender.com'
  from 'noreply@sender.com'
  to   'noreply@recipient.com'
  cc   'cc@sender.com'
  bcc  'alice@example.com'

  subject 'Welcome'
end

WelcomeMailer.new(configuration: configuration).call(locals)

Locals

The set of objects passed in the deliver call are called locals and are available inside the mailer and the template.

require 'hanami/mailer'
require 'ostruct'

user = OpenStruct.new(name: Luca', email: 'user@hanamirb.org')

class WelcomeMailer < Hanami::Mailer
  from    'noreply@sender.com'
  subject 'Welcome'
  to      ->(locals) { locals.fetch(:user).email }
end

WelcomeMailer.new(configuration: configuration).deliver(user: luca)

The corresponding erb file:

Hello <%= user.name %>!

Scope

All public methods defined in the mailer are accessible from the template:

require 'hanami/mailer'

class WelcomeMailer < Hanami::Mailer
  from    'noreply@sender.com'
  to      'noreply@recipient.com'
  subject 'Welcome'

  def greeting
    'Ahoy'
  end
end

<h2><%= greeting %></h2>

Template

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
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 < Hanami::Mailer
  template 'invoice'
end

# It will look for:
#  * app/templates/invoice.html.erb
#  * app/templates/invoice.txt.erb

Engines

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

Configuration

Hanami::Mailer can be configured with a DSL that determines its behavior. It supports a few options:

require "hanami/mailer"

configuration = Hanami::Mailer::Configuration.new do |config|
  # Set the root path where to search for templates
  # Argument: String, Pathname, #to_pathname, defaults to the current directory
  #
  config.root = "path/to/root"

  # Set the default charset for emails
  # Argument: String, defaults to "UTF-8"
  #
  config.default_charset = "iso-8859"

  # Set the delivery method
  # Argument: Symbol
  # Argument: Hash, optional configurations
  config.delivery_method = :stmp
end

Attachments

Attachments can be added with the following API:

class InvoiceMailer < Hanami::Mailer
  # ...
  before do |mail, locals|
    mail.attachments["invoice-#{locals.fetch(:invoice).number}.pdf"] = 'path/to/invoice.pdf'
  end
end

Delivery Method

The global delivery method is defined through the Hanami::Mailer configuration, as:

configuration = Hanami::Mailer::Configuration.new do |config|
  config.delivery_method = :smtp
end

configuration = Hanami::Mailer::Configuration.new do |config|
  config.delivery_method = :smtp, { address: "localhost", port: 1025 }
end

Builtin options are:

Exim (:exim)
Sendmail (:sendmail)
SMTP (:smtp, for local installations)
SMTP Connection (:smtp_connection, via Net::SMTP - for remote installations)
Test (:test, for testing purposes)

Custom Delivery Method

Developers can specify their own custom delivery policy:

require 'hanami/mailer'

class MandrillDeliveryMethod
  def initialize(options)
    @options = options
  end

  def deliver!(mail)
    # ...
  end
end

configuration = Hanami::Mailer::Configuration.new do |config|
  config.delivery_method = MandrillDeliveryMethod,
                           username: ENV['MANDRILL_USERNAME'],
                           password: ENV['MANDRILL_API_KEY']
end

The class passed to .delivery_method= must accept an optional set of options with the constructor (#initialize) and respond to #deliver!.

Multipart Delivery

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.new(configuration: configuration).deliver({})           # delivers both text and html templates
InvoiceMailer.new(configuration: configuration).deliver(format: :txt) # delivers only text template

Please note that they aren't both mandatory, but at least one of them MUST be present.

Versioning

Hanami::Mailer uses Semantic Versioning 2.0.0

Copyright

This project was formerly known as Lotus (lotus-mailer).

README.md Unescape Escape