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) %>

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

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 с кодированным в Base64 файлом книги file.pdf с именем файла 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, attachments и custom content type, как в этом примере:

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 на вложении, чтобы получить относительный путь ID содержимого для пути к источнику изображения:

<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.

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

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

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

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

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

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

Обработчики событий

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

class NotifierMailer < 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, чтобы заголовки были обработаны должным образом.

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

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

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

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

config.action_mailer.preview_path = "#{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 для обмена информацией и криптографический алгоритм сообщения Digest 5 для хеширования важной информации).

  • :enable_starttls - Использовать STARTTLS при подключении к SMTP-серверу и отказаться от него, если он не поддерживается. По умолчанию false.

  • :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/TLS (SMTPS: SMTP через прямое подключение TLS) для SMTP-соединения.

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

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

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

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

  • :arguments - Аргументы командной строки. По умолчанию -i с -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. Наиболее полезно для модульного и функционального тестирования.

• delivery_job - Класс задачи, используемый с deliver_later. По умолчанию ActionMailer::MailDeliveryJob.

• deliver_later_queue_name - Имя очереди, используемой с deliver_later.