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 копией файла book.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 и пользовательский тип содержимого, как в этом примере:

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.

Значения по умолчанию 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 - Позволяет использовать удаленный SMTP-сервер. Просто измените его со значения по умолчанию "localhost".

  • :port - В случае, если ваш SMTP-сервер не работает на порту 25, вы можете изменить его.

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

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

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

  • :authentication - Если ваш SMTP-сервер требует аутентификации, укажите здесь тип аутентификации. Это символ, и один из :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 gem для получения информации о требуемом интерфейсе для пользовательского агента доставки.

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

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

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