Базовый класс Action Mailer

Action Mailer позволяет отправлять электронные письма из приложения с помощью модели почтовой программы и представлений.

Модели почтовых программ

Чтобы использовать Action Mailer, необходимо создать модель почтовой программы.

$ bin/rails generate mailer Notifier

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

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

class NotifierMailer < 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

В методе почтовой программы доступны следующие методы:

• 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

Представления почтовых программ

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

Чтобы определить шаблон для почтовой программы, создайте файл .erb с тем же именем, что и метод в модели почтовой программы. Например, в почтовой программе, определённой выше, для создания письма будет использоваться шаблон app/views/notifier_mailer/welcome.text.erb.

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

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

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

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

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

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

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

Создание URL-адресов

В представлениях почтовых программ можно создавать URL-адреса с помощью url_for или именованных маршрутов. В отличие от контроллеров Action Pack, экземпляр почтовой программы не имеет контекста входящего запроса, поэтому для создания 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-адреса, относительно которого можно определить путь.

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

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

Можно также определить метод default_url_options в отдельных почтовых программах, чтобы переопределить эти значения по умолчанию для конкретной программы.

По умолчанию, если config.force_ssl равно true, для URL-адресов с хостами используется протокол HTTPS.

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

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

NotifierMailer.welcome(User.first).deliver_now # sends the email
mail = NotifierMailer.welcome(User.first)      # => an ActionMailer::MessageDelivery object
mail.deliver_now                               # generates and sends the email now

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

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

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

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

Обратите внимание: deliver_later выполнит ваш метод в фоновой задаче.

Экземпляр класса почтовой программы не создаётся. Вместо этого нужно вызвать метод, определённый непосредственно в самом классе. Ожидается, что все методы экземпляра будут возвращать объект сообщения для отправки.

Многокомпонентные письма

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

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

• signup_notification.text.erb

• signup_notification.html.erb

• signup_notification.xml.builder

• signup_notification.yml.erb

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

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

Вложения

Отправлять вложения в письмах просто:

class NotifierMailer < 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 с файлом file.pdf, закодированным в Base64, и именем файла free_book.pdf.

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

class NotifierMailer < 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-шаблоном. В этом случае необходимо добавить body, вложения и пользовательский тип содержимого, например:

class NotifierMailer < ApplicationMailer
  def welcome(recipient)
    attachments["free_book.pdf"] = File.read("path/to/file.pdf")
    mail(to: recipient,
         subject: "New account information",
         content_type: "text/html",
         body: "<html><body>Hello there</body></html>")
  end
end

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

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

class NotifierMailer < 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 предоставляет хуки для методов наблюдателя и перехватчика Mail. Они позволяют зарегистрировать классы, вызываемые на разных этапах жизненного цикла доставки письма.

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

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

Хэш параметров по умолчанию

Action Mailer задаёт для писем ряд разумных значений по умолчанию. Обычно их указывают в методе default внутри определения класса:

class NotifierMailer < 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 NotifierMailer < ApplicationMailer
  default 'Content-Transfer-Encoding' => '7bit',
          content_description: 'This is a description'
end

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

class NotifierMailer < ApplicationMailer
  default 'X-Special-Header' => Proc.new { my_method }, to: -> { @inviter.email_address }

  private
    def my_method
      'some complex call'
    end
end

Обратите внимание: proc/lambda вычисляется сразу в начале создания почтового сообщения. Поэтому если установить значение в хэше параметров по умолчанию с помощью proc, а затем установить то же значение в методе почтовой программы, значение из хэша будет перезаписано методом почтовой программы.

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

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

Обратные вызовы

Для настройки сообщений можно указать обратные вызовы с помощью before_action и after_action, а для обёртывания процесса доставки — с помощью before_deliver и after_deliver. Например, если нужно добавить стандартные встроенные вложения и вести журнал доставки для всех сообщений, отправляемых определённым классом почтовой программы:

class NotifierMailer < ApplicationMailer
  before_action :add_inline_attachment!
  after_deliver :log_delivery

  def welcome
    mail
  end

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

    def log_delivery
      Rails.logger.info "Sent email with message id '#{message.message_id}' at #{Time.current}."
    end
end

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

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

Обработка ошибок

Блоки rescue внутри метода почтовой программы не могут перехватывать ошибки, возникающие вне этапа рендеринга, например ошибки десериализации записи в фоновой задаче или ошибки сторонней службы доставки почты.

Чтобы перехватывать ошибки, возникающие на любом этапе отправки письма, используйте rescue_from:

class NotifierMailer < ApplicationMailer
  rescue_from ActiveJob::DeserializationError do
    # ...
  end

  rescue_from "SomeThirdPartyService::ApiError" do
    # ...
  end

  def notify(recipient)
    mail(to: recipient, subject: "Notification")
  end
end

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

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

class NotifierMailerPreview < ActionMailer::Preview
  def welcome
    NotifierMailer.welcome(User.first)
  end
end

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

config.action_mailer.preview_paths << "#{Rails.root}/lib/mailer_previews"

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

Объекты Previews также можно перехватывать аналогично доставляемым письмам, зарегистрировав перехватчик предварительного просмотра с методом 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 — позволяет использовать удалённый почтовый сервер. Для этого измените значение по умолчанию — «localhost».

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

  • :domain — здесь можно указать домен HELO, если это необходимо.

  • :user_name — если для почтового сервера требуется аутентификация, укажите здесь имя пользователя.

  • :password — если для почтового сервера требуется аутентификация, укажите здесь пароль.

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

  • :enable_starttls — использовать STARTTLS при подключении к SMTP-серверу и завершать работу с ошибкой, если протокол не поддерживается. По умолчанию задано значение false. Требуется версия 2.7 или выше гем-пакета Mail.

  • :enable_starttls_auto — проверять, включён ли STARTTLS на SMTP-сервере, и начинать его использовать, если это так. По умолчанию задано значение true.

  • :openssl_verify_mode — при использовании TLS можно задать способ проверки сертификата OpenSSL. Это особенно полезно, если необходимо проверить самоподписанный сертификат и/или сертификат с подстановочными знаками. Можно указать имя константы проверки OpenSSL ('none' или 'peer') либо непосредственно константу (OpenSSL::SSL::VERIFY_NONE или OpenSSL::SSL::VERIFY_PEER).

  • :ssl/:tls Позволяет SMTP-подключению использовать SMTP/TLS (SMTPS: SMTP через прямое TLS-подключение).

  • :open_timeout Количество секунд ожидания при попытке установить соединение.

  • :read_timeout Количество секунд ожидания до истечения времени ожидания вызова read(2).

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

  • :location — расположение исполняемого файла sendmail. По умолчанию — /usr/sbin/sendmail.

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

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

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

• raise_delivery_errors — следует ли генерировать ошибки, если не удалось доставить письмо.

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

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

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

• delivery_job — класс задачи, используемый вместе с deliver_later. Почтовые программы могут задать здесь пользовательскую задачу доставки. По умолчанию используется ActionMailer::MailDeliveryJob.

• deliver_later_queue_name — имя очереди, используемой deliver_later со значением delivery_job по умолчанию. Почтовые программы могут задать пользовательское имя очереди.