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

Модели рассылки

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

$ rails generate mailer Notifier

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

class Notifier < ActionMailer::Base
  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'. Обратите внимание, что, хотя большинство полей, таких как To: From:, могут появляться только один раз в заголовке письма, другие поля, такие как X-Anything, могут появляться несколько раз. Если вы хотите изменить поле, которое может появляться несколько раз, необходимо сначала установить его в значение nil, чтобы Mail понял, что вы его заменяете, а не добавляете ещё одно поле с таким же именем.

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

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

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

Метод mail, если ему не передан блок, просмотрит ваши представления и отправит все представления с тем же именем, что и метод, поэтому вышеуказанное действие также отправит файл представления welcome.text.erb, а также файл представления welcome.text.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/welcome.text.erb будет использоваться для создания письма.

Переменные, определенные в модели, доступны как переменные экземпляра в представлении.

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

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

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

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" }

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

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

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

Notifier.welcome(david).deliver # sends the email
mail = Notifier.welcome(david)  # => a Mail::Message object
mail.deliver                    # sends the email

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

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

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

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

• signup_notification.text.erb

• signup_notification.html.erb

• signup_notification.xml.builder

• signup_notification.yaml.erb

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

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

Вложения

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

class ApplicationMailer < ActionMailer::Base
  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 копией файла.pdf книги с именем файла free_book.pdf.

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

class ApplicationMailer < ActionMailer::Base
  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 ApplicationMailer < ActionMailer::Base
  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.

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

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

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

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

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

  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 Notifier < ActionMailer::Base
  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

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

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

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

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

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

Методы должны возвращать объект Mail::Message, который может быть сгенерирован вызовом метода mailer без дополнительных deliver. Путь к каталогу предварительных просмотров 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 - В случае, если ваш SMTP-сервер не работает на порту 25, вы можете изменить его.

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

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

  • :password - Если ваш SMTP-сервер требует аутентификации, укажите пароль в этой настройке.

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

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

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