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

Вы также можете определить метод 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 копией файла book.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["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 предоставляет некоторые интеллектуальные значения по умолчанию для ваших писем, которые обычно указываются в методе по умолчанию внутри определения класса:

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 на экземпляре работающего сервера разработки.

Предварительные просмотры также можно перехватывать аналогичным образом, как и доставки, зарегистрировав перехватчик предварительного просмотра, имеющий метод 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') или напрямую константу (OpenSSL::SSL::VERIFY_NONE или OpenSSL::SSL::VERIFY_PEER).

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

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

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

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

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