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

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

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

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

По умолчанию, когда 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.

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

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-элементами. Это полезно, если вы хотите отобразить корпоративный логотип или фото.

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.

Значения по умолчанию для 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 в хэш по умолчанию, так что вы можете определить методы, которые оцениваются по мере генерации сообщения:

class NotifierMailer < ApplicationMailer
  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 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, который можно сгенерировать, вызвав метод 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 - Позволяет использовать удалённый почтовый сервер. Просто измените его с значения по умолчанию «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 с -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. Наиболее полезно для модульных и функциональных тестов.

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