Action Mailer позволяет отправлять электронные письма из вашего приложения, используя модель mailer и представления.

Модели Mailer

Для использования Action Mailer необходимо создать модель mailer.

$ rails generate mailer Notifier

Сгенерированная модель наследуется от ApplicationMailer, которая, в свою очередь, наследуется от ActionMailer::Base. Модель mailer определяет методы, используемые для генерации электронного сообщения. В этих методах можно настраивать переменные, используемые в представлениях mailer, параметры самого письма, такие как адрес :from, и вложения.

class ApplicationMailer < ActionMailer::Base
  default from: 'from@exmaple.com'
  layout 'mailer'
end

class Notifier < ApplicationMailer
  default from: 'no-reply@example.com',
          return_path: 'system@example.com'

  def welcome(recipient)
    @account = recipient
    mail(to: recipient.email_address_with_name,
         bcc: ["bcc@example.com", "Order Watcher <watcher@example.com>"])
  end
end

Внутри метода mailer у вас есть доступ к следующим методам:

• attachments[]= - Позволяет добавить вложения к вашему письму интуитивным способом; attachments['filename.png'] = File.read('path/to/filename.png')

• attachments.inline[]= - Позволяет добавить встроенное вложение в письмо аналогичным образом, как и attachments[]=

• headers[]= - Позволяет указать любой заголовок поля в вашем письме, например, headers['X-No-Spam'] = 'True'. Обратите внимание, что объявление заголовка несколько раз добавит несколько полей с одинаковым именем. Прочитайте документацию headers для получения дополнительной информации.

• headers(hash) - Позволяет указать несколько заголовков в вашем письме, например, headers({'X-No-Spam' => 'True', 'In-Reply-To' => '1234@message.id'})

• mail - Позволяет указать электронное письмо для отправки.

Хэш, переданный методу mail, позволяет указать любой заголовок, который будет принять Mail::Message (любой допустимый заголовок электронной почты, включая необязательные поля).

Метод mail, если ему не передан блок, проверит ваши представления и отправит все представления с тем же именем, что и метод, таким образом, вышеупомянутое действие также отправит файл представления welcome.text.erb, а также файл представления welcome.html.erb в электронном письме multipart/alternative.

Если вы хотите явно отобразить только определенные шаблоны, передайте блок:

mail(to: user.email) do |format|
  format.text
  format.html
end

Синтаксис блока также полезен для предоставления информации, специфичной для части:

mail(to: user.email) do |format|
  format.text(content_transfer_encoding: "base64")
  format.html
end

Или даже для отображения специального представления:

mail(to: user.email) do |format|
  format.text
  format.html { render "some_other_template" }
end

Представления Mailer

Как и Action Controller, каждый класс mailer имеет соответствующую директорию представлений, в которой каждый метод класса ищет шаблон с его именем.

Для определения шаблона, используемого с рассылкой, создайте файл .erb с тем же именем, что и метод в вашей модели mailer. Например, в определенной выше модели mailer шаблон в app/views/notifier/welcome.text.erb будет использоваться для генерации электронного письма.

Переменные, определенные в методах вашей модели mailer, доступны как переменные экземпляра в соответствующих представлениях.

По умолчанию письма отправляются в формате простого текста, поэтому пример представления для нашей модели может выглядеть так:

Hi <%= @account.name %>,
Thanks for joining our service! Please check back often.

Вы даже можете использовать помощники Action View в этих представлениях. Например:

You got a new note!
<%= truncate(@note.body, length: 25) %>

Если вам нужно получить доступ к теме, отправителю или получателям в представлении, вы можете сделать это через объект сообщения:

You got a new note from <%= message.from %>!
<%= truncate(@note.body, length: 25) %>

Генерация URL-адресов

URL-адреса можно генерировать в представлениях mailer, используя url_for или именованные маршруты. В отличие от контроллеров из Action Pack, экземпляр mailer не имеет никакого контекста о входящем запросе, поэтому вам нужно предоставить все необходимые детали для генерации URL-адреса.

При использовании url_for вам потребуется предоставить :host, :controller, и :action:

<%= url_for(host: "example.com", controller: "welcome", action: "greeting") %>

При использовании именованных маршрутов вам нужно только предоставить :host:

<%= users_url(host: "example.com") %>

Вы должны использовать стиль named_route_url (который генерирует абсолютные URL-адреса) и избегать использования стиля named_route_path (который генерирует относительные URL-адреса), так как клиенты, читающие письмо, не будут иметь представления о текущем URL-адресе для определения относительного пути.

Также можно установить хост по умолчанию, который будет использоваться во всех mailers, установив опцию :host в качестве параметра конфигурации в config/application.rb:

config.action_mailer.default_url_options = { host: "example.com" }

Когда вы решите установить значение по умолчанию :host для своих mailers, вам необходимо убедиться, что вы используете опцию only_path: false при использовании url_for. Поскольку помощник представления url_for по умолчанию генерирует относительные URL-адреса, когда опция :host не указана явно, передача only_path: false гарантирует генерацию абсолютных URL-адресов.

Отправка письма

После определения действия mailer и шаблона вы можете доставить свое сообщение или создать его и сохранить для последующей доставки:

Notifier.welcome(User.first).deliver_now # sends the email
mail = Notifier.welcome(User.first)      # => an ActionMailer::MessageDelivery object
mail.deliver_now                    # sends the email

Класс ActionMailer::MessageDelivery является оболочкой вокруг объекта Mail::Message. Если вам нужен прямой доступ к объекту Mail::Message, вы можете вызвать метод message на объекте ActionMailer::MessageDelivery.

Notifier.welcome(User.first).message     # => a Mail::Message object

Action Mailer хорошо интегрирован с Active Job, поэтому вы можете отправлять электронные письма в фоновом режиме (например, вне цикла запроса-ответа, чтобы пользователь не должен был ждать):

Notifier.welcome(User.first).deliver_later # enqueue the email sending to Active Job

Вы никогда не создаёте экземпляр класса mailer. Вместо этого, вы просто вызываете метод, который вы определили для самого класса.

Письма с несколькими частями

Сообщения с несколькими частями также могут использоваться неявно, потому что Action Mailer автоматически обнаружит и использует шаблоны с несколькими частями, где каждый шаблон называется по имени действия, после которого следует тип контента. Каждый такой обнаруженный шаблон будет добавлен как отдельная часть сообщения.

Например, если существуют следующие шаблоны:

• signup_notification.text.erb

• signup_notification.html.erb

• signup_notification.xml.builder

• signup_notification.yml.erb

Каждый из них будет отображен и добавлен как отдельная часть сообщения с соответствующим типом контента. Тип контента для всего сообщения автоматически устанавливается в multipart/alternative, что указывает на то, что электронное письмо содержит несколько различных представлений одного и того же тела электронного письма. Те же переменные экземпляра, определенные в действии, передаются всем шаблонам электронных писем.

Неявное отображение шаблонов не выполняется, если какие-либо вложения или части были добавлены в электронное письмо. Это означает, что вам нужно вручную добавить каждую часть в письмо и установить тип контента письма в multipart/alternative.

Вложения

Отправка вложений в электронные письма проста:

class Notifier < ApplicationMailer
  def welcome(recipient)
    attachments['free_book.pdf'] = File.read('path/to/file.pdf')
    mail(to: recipient, subject: "New account information")
  end
end

Это (если в директории представления были бы и шаблон welcome.text.erb и шаблон welcome.html.erb) отправит полное multipart/mixed электронное письмо с двумя частями: первой частью будет multipart/alternative с текстовой и HTML-частью электронного письма внутри, а второй частью будет application/pdf с кодированным в Base64 копией файла book.pdf с именем файла free_book.pdf.

Если вам нужно отправлять вложения без содержимого, необходимо создать для них пустое представление или добавить пустой параметр тела, как в этом примере:

class Notifier < ApplicationMailer
  def welcome(recipient)
    attachments['free_book.pdf'] = File.read('path/to/file.pdf')
    mail(to: recipient, subject: "New account information", body: "")
  end
end

Встроенные вложения

Вы также можете указать, что файл должен отображаться встроенным образом вместе с другим HTML. Это полезно, если вы хотите отобразить корпоративный логотип или фотографию.

class Notifier < ApplicationMailer
  def welcome(recipient)
    attachments.inline['photo.png'] = File.read('path/to/photo.png')
    mail(to: recipient, subject: "Here is what we look like")
  end
end

Затем, чтобы сослаться на изображение в представлении, вы создаёте файл welcome.html.erb и вызываете метод image_tag, передавая вложение, которое вы хотите отобразить, а затем вызываете url на вложении, чтобы получить относительный путь к идентификатору содержимого для источника изображения:

<h1>Please Don't Cringe</h1>

<%= image_tag attachments['photo.png'].url -%>

Так как мы используем метод image_tag Action View, вы можете передать любые другие желаемые параметры:

<h1>Please Don't Cringe</h1>

<%= image_tag attachments['photo.png'].url, alt: 'Our Photo', class: 'photo' -%>

Наблюдение и перехват писем

Action Mailer предоставляет крючки в методы наблюдения и перехвата почты. Это позволяет вам регистрировать классы, которые вызываются во время жизненного цикла доставки почты.

Класс наблюдателя должен реализовать метод :delivered_email(message), который будет вызываться один раз для каждого отправленного электронного письма после отправки электронного письма.

Класс перехватчика должен реализовать метод :delivering_email(message), который будет вызываться перед отправкой электронного письма, позволяя вам внести изменения в письмо перед доставкой агентам. Ваш класс должен внести необходимые изменения непосредственно в переданный объект Mail::Message.

Значение Hash по умолчанию

Action Mailer предоставляет некоторые разумные значения по умолчанию для ваших писем, которые обычно задаются в методе по умолчанию внутри определения класса:

class Notifier < ApplicationMailer
  default sender: 'system@example.com'
end

Вы можете передать любое значение заголовка, которое принимает Mail::Message. Из коробки, ActionMailer::Base устанавливает следующее:

• mime_version: "1.0"

• charset: "UTF-8",

• content_type: "text/plain",

• parts_order: [ "text/plain", "text/enriched", "text/html" ]

parts_order и charset на самом деле не являются допустимыми полями заголовка Mail::Message, но Action Mailer переводит их соответствующим образом и устанавливает правильные значения.

Поскольку вы можете передать любой заголовок, вам нужно либо заключить заголовок в строку, либо передать его как символьное выражение с подчеркиванием, поэтому следующее будет работать:

class Notifier < ApplicationMailer
  default 'Content-Transfer-Encoding' => '7bit',
          content_description: 'This is a description'
end

Наконец, Action Mailer также поддерживает передачу объектов Proc в хэш по умолчанию, поэтому вы можете определить методы, которые будут вычисляться по мере генерации сообщения:

class Notifier < ApplicationMailer
  default 'X-Special-Header' => Proc.new { my_method }

  private

    def my_method
      'some complex call'
    end
end

Обратите внимание, что процедура вычисляется в самом начале генерации почтового сообщения, поэтому если вы устанавливаете что-то в значениях по умолчанию с помощью процедуры, а затем устанавливаете то же самое внутри вашего метода mailer, метод mailer перезапишет его.

Также можно установить эти параметры по умолчанию, которые будут использоваться во всех mailers, через параметр конфигурации default_options= в config/application.rb:

config.action_mailer.default_options = { from: "no-reply@example.org" }

Обработчики

Вы можете указать обработчики, используя before_action и after_action для настройки ваших сообщений. Это может быть полезно, например, когда вы хотите добавить встроенные вложения по умолчанию для всех сообщений, отправленных определенным классом mailer:

class Notifier < ApplicationMailer
  before_action :add_inline_attachment!

  def welcome
    mail
  end

  private

    def add_inline_attachment!
      attachments.inline["footer.jpg"] = File.read('/path/to/filename.jpg')
    end
end

Обработчики в Action Mailer реализованы с помощью AbstractController::Callbacks, поэтому вы можете определить и настроить обработчики так же, как вы бы использовали обработчики в классах, наследуемых от ActionController::Base.

Обратите внимание, что если у вас нет особой причины, вы должны предпочесть использовать before_action вместо after_action в ваших классах Action Mailer, чтобы заголовки были обработаны правильно.

Предварительный просмотр писем

Вы можете визуально просмотреть шаблоны писем, добавив файл предварительного просмотра mailer в ActionMailer::Base.preview_path. Поскольку большинство писем что-то делают с данными базы данных, вам нужно написать сценарии для загрузки сообщений с фиктивными данными:

class NotifierPreview < ActionMailer::Preview
  def welcome
    Notifier.welcome(User.first)
  end
end

Методы должны возвращать объект Mail::Message, который можно сгенерировать, вызвав метод mailer без дополнительных deliver_now / deliver_later. Путь к каталогу с предварительными просмотрами mailer можно настроить с помощью опции preview_path, по умолчанию значение которой test/mailers/previews.

config.action_mailer.preview_path = "#{Rails.root}/lib/mailer_previews"

Обзор всех предварительных просмотров доступен по адресу http://localhost:3000/rails/mailers на работающем экземпляре сервера разработки.

Предварительные просмотры также можно перехватить аналогичным способом, как и доставки, зарегистрировав обработчик предварительных просмотров, который имеет метод previewing_email.

class CssInlineStyler
  def self.previewing_email(message)
    # inline CSS styles
  end
end

config.action_mailer.preview_interceptors :css_inline_styler

Обратите внимание, что обработчики необходимо регистрировать как в register_interceptor, так и в register_preview_interceptor, если они должны работать как при отправке, так и при предварительном просмотре электронных писем.

Параметры конфигурации

Эти параметры задаются на уровне класса, как и ActionMailer::Base.raise_delivery_errors = true

• default_options - Вы можете передать его как на уровне класса, так и внутри самого класса, как указано в предыдущем разделе.

• logger - Логгер используется для генерации информации о выполнении рассылки, если доступен. Может быть установлен на nil для отключения ведения журнала. Совместим с собственными логгерами Ruby Logger и логгерами Log4r.

• smtp_settings - Позволяет детальную настройку метода доставки :smtp.

  • :address - Позволяет использовать удаленный SMTP-сервер. Просто измените его значение с по умолчанию “localhost”.

  • :port - На случай, если ваш почтовый сервер не работает на порту 25, вы можете изменить его.

  • :domain - Если вам нужно указать домен HELO, вы можете сделать это здесь.

  • :user_name - Если ваш почтовый сервер требует аутентификации, задайте имя пользователя в этом параметре.

  • :password - Если ваш почтовый сервер требует аутентификации, задайте пароль в этом параметре.

  • :authentication - Если ваш почтовый сервер требует аутентификации, укажите здесь тип аутентификации. Это символ, и один из :plain (будет отправлять пароль в кодировке Base64), :login (будет отправлять пароль в кодировке Base64) или :cram_md5 (объединяет механизм Challenge/Response для обмена информацией и криптографический алгоритм Message Digest 5 для хэширования важной информации).

  • :enable_starttls_auto - Обнаруживает, включен ли STARTTLS на вашем SMTP-сервере, и начинает использовать его. По умолчанию true.

  • :openssl_verify_mode - При использовании TLS можно настроить, как OpenSSL проверяет сертификат. Это очень полезно, если вам нужно валидировать самозаверяемый и/или сертификат с подстановочными символами. Вы можете использовать имя константы OpenSSL для проверки ('none', 'peer', 'client_once', 'fail_if_no_peer_cert') или напрямую константу (OpenSSL::SSL::VERIFY_NONE, OpenSSL::SSL::VERIFY_PEER, …).

• sendmail_settings - Позволяет переопределить параметры для метода доставки :sendmail.

  • :location - Путь к исполняемому файлу sendmail. По умолчанию /usr/sbin/sendmail.

  • :arguments - Аргументы командной строки. По умолчанию -i -t с -f sender@address автоматически добавленным перед отправкой сообщения.

• file_settings - Позволяет переопределить параметры для метода доставки :file.

  • :location - Каталог, в который будут записываться электронные письма. По умолчанию tmp/mails приложения.

• raise_delivery_errors - Указывает, следует ли генерировать исключения, если электронное письмо не доставлено.

• delivery_method - Определяет метод доставки. Возможные значения: :smtp (по умолчанию), :sendmail, :test, и :file. Или вы можете указать объект пользовательского метода доставки, например MyOwnDeliveryMethodClass. См. документацию Mail gem по интерфейсу, который необходимо реализовать для пользовательского агента доставки.

• perform_deliveries - Определяет, будут ли электронные письма фактически отправляться из Action Mailer, когда вы вызываете .deliver для сообщения электронной почты или метода Action Mailer. По умолчанию включено, но может быть выключено для упрощения функционального тестирования.

• deliveries - Содержит массив всех отправленных электронных писем через Action Mailer с delivery_method :test. Наиболее полезно для модульного и функционального тестирования.