Começando a usar Action Mailer

1 O que é o Action Mailer?

Action Mailer permite que você envie emails direto da sua aplicação usando as classes e Mailer views

1.1 Mailers são Semelhantes a Controllers

Eles herdam do ActionMailer::Base e se encontram na app/mailers. Os Mailers também funcionam de maneira muito semelhante aos controllers. Alguns exemplos de semelhanças são mostrados abaixo. Mailers tem:

Actions, e também, views associadas que aparecem em app/views.
Variáveis de instância acessíveis nas views.
A capacidade de utilizar layouts e partials.
A capacidade de acessar um hash de parâmetros.

2 Enviando E-mails

Esta seção irá te guiar no processo de criação de um Mailer e sua view.

2.1 Passo a Passo para Gerar um Mailer

2.1.1 Criando um Mailer

$ bin/rails generate mailer User
create  app/mailers/user_mailer.rb
create  app/mailers/application_mailer.rb
invoke  erb
create    app/views/user_mailer
create    app/views/layouts/mailer.text.erb
create    app/views/layouts/mailer.html.erb
invoke  test_unit
create    test/mailers/user_mailer_test.rb
create    test/mailers/previews/user_mailer_preview.rb

# app/mailers/application_mailer.rb
class ApplicationMailer < ActionMailer::Base
  default from: "[email protected]"
  layout 'mailer'
end

# app/mailers/user_mailer.rb
class UserMailer < ApplicationMailer
end

Como pôde ver no exemplo acima, você pode gerar mailers como faz com outros tipos de arquivos no Rails.

Se você prefere não usar um generator, você pode criar esses arquivos por si só dentro de app/mailers/, só não se esqueça de adicionar a herança com ActionMailer::Base aos mailers:

class MyMailer < ActionMailer::Base
end

2.1.2 Editando o Mailer

Mailers têm métodos chamados actions e usam views para estruturar seu conteúdo. Onde um controller gera conteúdo como HTML para enviar de volta à um cliente, o Mailer cria uma mensagem para ser entregue por e-mail.

app/mailers/user_mailer.rb contém um mailer vazio:

class UserMailer < ApplicationMailer
end

Vamos adicionar um método chamado welcome_email, que enviará um e-mail para o endereço de e-mail registrado pelo usuário.

class UserMailer < ApplicationMailer
  default from: '[email protected]'

  def welcome_email
    @user = params[:user]
    @url  = 'http://exemplo.com/login'
    mail(to: @user.email, subject: 'Boas vindas ao nosso incrível site!')
  end
end

Uma breve explicação sobre os itens apresentados no método acima. Para uma lista completa de todas as opções disponíveis, por favor, dê uma olhada mais abaixo na seção: Lista completa de atributos de configuração do Action Mailer.

[default Hash][] — Está é a Hash padrão com valores que serão usados em todos os e-mail enviados por este mailer. Neste exemplo nós configuramos o :from (Remetente, quem envia) para um valor padrão que será usado em todas as mensagens enviadas por está classe. Está configuração pode ser sobrescrita.
mail — O próprio e-mail, aqui nós estamos passando os parâmetros :to (Destinatário, quem recebe) e :subject (Assunto do e-mail) ao cabeçalho.

2.1.3 Criando uma View para nosso Mailer

Crie um arquivo com o nome welcome_email.html.erb em app/views/user_mailer/. Este será o modelo que usaremos para nosso e-mail, formatado usando HTML:

<!DOCTYPE html>
<html>
  <head>
    <meta content='text/html; charset=UTF-8' http-equiv='Content-Type' />
  </head>
  <body>
    <h1>Boas vindas ao site exemplo.com, <%= @user.name %></h1>
    <p>
      Você concluiu seu cadastro com sucesso,
      seu nome de usuário é: <%= @user.login %>.<br>
    </p>
    <p>
      Para iniciar sua seção no site clique no link a seguir: <%= @url %>.
    </p>
    <p>Agradecemos por se juntar à nós! Tenha um ótimo dia!</p>
  </body>
</html>

Vamos criar também um modelo usando somente texto para este e-mail. Nem todos os programas de e-mail leem HTML, então enviar os dois formatos é uma boa prática. Para isto criaremos um arquivo com o nome welcome_email.text.erb em app/views/user_mailer/:

Boas vindas ao site exemplo.com, <%= @user.name %>
===============================================

Você concluiu seu cadastro com sucesso,
seu nome de usuário é: <%= @user.login %>.

Para iniciar sua seção no site clique no link a seguir: <%= @url %>.

Agradecemos por se juntar à nós! Tenha um ótimo dia!

Quando você chamar o método mail, ActionMailer detectará que existem dois modelos para esse e-mail (Um em HTML e outro somente texto) e automaticamente irá gerar um multipart/alternative (Opção que indica ao programa de e-mail que essa mensagem tem uma versão em HTML e outra em somente texto) e-mail.

2.1.4 Chamando o Mailer

Mailers são somente outra maneira de renderizar uma view. Ao invés de renderizar uma view e envia-la usando o protocolo HTTP, um Mailer envia através dos protocolos de e-mail. Por esse motivo, faz sentido, para o exemplo anterior, que o controller informe ao mailer para enviar uma mensagem assim que um usuário complete seu cadastro com sucesso.

Configurar isto é muito simples.

Primeiro, criaremos um scaffold (esqueleto) para nosso model User:

$ bin/rails generate scaffold user name e-mail login
$ bin/rails db:migrate

Agora que já temos o model para nossos usuários, podemos começar a criar a funcionalidade. Para isso vamos editar o arquivo app/controllers/users_controller.rb para chamar o UserMailer para enviar um e-mail ao novo usuário registrado. Vamos editar a action create inserindo a seguinte chamada: UserMailer.with(user: @user).welcome_email logo após o usuário ter sido salvo com sucesso.

Vamos enfileirar o email a ser enviado usando deliver_later, que é apoiado pelo Active Job. Dessa forma, a action do controller pode continuar sem aguardando a conclusão do envio.

class UsersController < ApplicationController
  # ...

  # POST /users or /users.json
  def create
    @user = User.new(user_params)

    respond_to do |format|
      if @user.save
        # Diz ao UserMailer para enviar o _welcome e-mail_ caso o usuário seja salvo
        UserMailer.with(user: @user).welcome_email.deliver_later

        format.html { redirect_to(@user, notice: 'Usuário foi criado com sucesso.') }
        format.json { render json: @user, status: :created, location: @user }
      else
        format.html { render action: 'new' }
        format.json { render json: @user.errors, status: :unprocessable_entity }
      end
    end
  end

  # ...
end

O comportamento padrão do Active Job é executar os serviços de maneira assíncrona, usando o adaptador :async. Então você pode usar o método deliver_later para enviar os e-mail de maneira assíncrona. O adaptador padrão do Active Job executa os serviços em um processo Thread Pool. Está abordagem é boa para os ambientes de desenvolvimento e teste, pois não requerem nenhuma infraestrutura externa/complexa, porém é uma abordagem ruim para o ambiente de produção, pois caso o sistema seja reiniciado você pode perder os registros desses serviços. Se você precisar de uma solução para que esses serviços sejam persistidos, de modo a evitar possíveis perdas, você precisará de um serviço a parte que tenha essa funcionalidade, exemplos: Sidekiq, Resque etc.

Se você deseja que os e-mail sejam enviados no mesmo tempo que chamar o Mailer, simplesmente chame deliver_now:

class SendWeeklySummary
  def run
    User.find_each do |user|
      UserMailer.with(user: user).weekly_summary.deliver_now
    end
  end
end

Qualquer chave-valor passado para o with se torna parte da Hash params que será usado na action do Mailer. Então with(user: @user, account: @user.account) cria params[:user] e params[:account] disponíveis na action do Mailer. Como acontece nos controllers que também tem params.

O método welcome_email tem como retorno um objeto do tipo ActionMailer::MessageDelivery que você pode encadear os métodos deliver_now ou deliver_later para assim ele se enviar como um e-mail. O objeto ActionMailer::MessageDelivery é um wrapper (Embrulho) para a classe Mail::Message. Se você quiser inspecionar, alterar, ou fazer qualquer coisa com o objeto Mail::Message você pode acessa-lo através do método message do objeto ActionMailer::MessageDelivery.

2.2 Codificação Automática no Header

Action Mailer gerencia automaticamente a codificação de caracteres multibytes (Caracteres asiáticos, emojis etc) dentro do cabeçalho e corpo.

Para exemplos mais complexos como definir uma lista alternativa de caracteres ou codificar o texto de maneira diferente, use essa biblioteca como referência: Mail.

2.3 Lista Completa de Métodos do Action Mailer

Existem apenas três métodos que você precisa para enviar qualquer mensagem de e-mail:

headers — Especifica qualquer cabeçalho no e-mail como você desejar. Você pode passar uma hash contendo os campos do cabeçalho seguindo o padrão chave: valor, ou você pode chamar a variável headers[:field_name] = value.
attachments — Permite adicionar anexos ao e-mail. Exemplo: attachments['file-name.jpg'] = File.read('file-name.jpg') que irá adicionar o arquivo file-name.jpg como anexo no e-mail.
mail — Cria o e-mail de fato. Você pode usar a hash headers como um dos parâmetros. mail vai criar o e-mail, tanto em texto puro ou multipart, dependendo dos modelos disponíveis que você definiu.

2.3.1 Adicionando Anexos

Com o Action Mailer é muito fácil trabalhar com anexos.

Passe o nome do arquivo e o conteúdo para o Action Mailer e a Mail gem irá descobrir o mime_type do arquivo, define a codificação (encoding) e criar o anexo.
```
attachments['filename.jpg'] = File.read('/caminho/para/o/arquivo.jpg')
```

Quando o método mail for invocado, enviará um e-mail no modo multipart com o anexo, corretamente configurado, sendo o anexo a primeira parte como multipart/mixed e a mensagem sendo a segunda com multipart/alternative com o texto e o HTML do e-mail.

O anexo será codificado usando Base64 pelo Mail. Se você precisar de algo diferente, codifique previamente o conteúdo e adicione o anexo e qual a codificação na hash attachments.

Passe o nome do arquivo, cabeçalhos específicos e o conteúdo e o Action Mailer e Mail irão usar as configurações:

encoded_content = SpecialEncode(File.read('/caminho/para/o/arquivo.jpg'))
attachments['arquivo.jpg'] = {
  mime_type: 'application/gzip',
  encoding: 'SpecialEncoding',
  content: encoded_content
}

Se você especificar a codificação, Mail assumirá que o conteúdo já está codificado e não irá codificar usando o padrão Base64.

2.3.2 Criando Anexos dentro da Mensagem de E-mail (Inline)

Action Mailer 3.0 cria anexos dentro da mensagem de e-mail, algo que antes da versão 3.0 envolvia algumas gambiarras, de maneira muito simples e trivia como sempre deveria ter sido.

Primeiro, para informar ao Mail que o anexo deve ser enviado dentro da própria mensagem você pode encadear o método #inline no attachments dentro da action do seu Mailer:
```
def welcome
  attachments.inline['image.jpg'] = File.read('/caminho/para/a/imagem.jpg')
end
```
Na view, você só precisa especificar qual o anexo dentro de attachments, que é uma hash, você quer mostrar, encadeando o método url no anexo irá retornar o endereço do anexo e você pode passar o resultado para o método image_tag que renderiza uma imagem, veja o exemplo abaixo:
```
<p>Olá! Aqui está nossa imagem</p>

<%= image_tag attachments['imagem.jpg'].url %>
```
Como isso é uma chamada normal ao método image_tag você pode passar uma hash de opções após a URL do anexo como você faria para qualquer outra imagem:
```
<p>Olá! Aqui está nossa imagem</p>

<%= image_tag attachments['imagem.jpg'].url, alt: 'Minha Foto', class: 'fotos' %>
```

2.3.3 Enviando E-mail para Vários Destinatários

É possível enviar e-mail para um ou mais destinatários usando uma mensagem de e-mail (Por exemplo: notificando os administradores que houve um novo cadastro) bastando configurar uma lista de e-mails no parâmetro :to. Essa lista de e-mails pode ser um Array de endereços de e-mails ou uma String contendo todos os e-mails separados por vírgulas.

class AdminMailer < ApplicationMailer
  default to: -> { Admin.pluck(:email) },
          from: '[email protected]'

  def new_registration(user)
    @user = user
    mail(subject: "Novo usuário cadastrado: #{@user.email}")
  end
end

class AdminMailer < ApplicationMailer
  default to: '[email protected],[email protected],[email protected]',
          from: '[email protected]'

  def new_registration(user)
    @user = user
    mail(subject: "Novo usuário cadastrado: #{@user.email}")
  end
end

O mesmo formato pode ser usado para enviar e-mails com cópia (Cc:) ou com cópia oculta (Cco: ou Bcc: em inglês), adicione :cc ou :bcc para enviar seguindo os padrões descritos acima.

2.3.4 Enviando E-mail com Nome

Em alguns momentos você deseja exibir o nome da pessoa que enviou a mensagem ao invés de mostrar somente o e-mail. Você pode usar email_address_with_name para isso:

def welcome_email
  @user = params[:user]
  mail(
    to: email_address_with_name(((((nc(@user.email, @user.name),
    subject: 'Welcome to My Awesome Site'
  )
end

A mesma técnica funciona para especificar um nome de remetente:

class UserMailer < ApplicationMailer
  default from: email_address_with_name('[email protected]', 'Example Company Notifications')
end

Se o nome for uma string em branco, ele retornará apenas o endereço.

2.4 Views de Mailer

As views de um Mailer ficam no diretório app/views/nome_da_classe_do_mailer. A view específica do mailer é reconhecida pela classe pois seu nome é o mesmo do método. No exemplo anterior, nossa view para o método welcome_email estará em app/views/user_mailer/welcome_email.html.erb, para a versão em HTML e em welcome_email.text.erb para a versão em texto simples.

Para mudar a mailer view padrão da sua action, é preciso fazer algo como por exemplo:

class UserMailer < ApplicationMailer
  default from: '[email protected]'

  def welcome_email
    @user = params[:user]
    @url  = 'http://example.com/login'
    mail(to: @user.email,
         subject: 'Bem vindo ao meu site!',
         template_path: 'notifications',
         template_name: 'another')
  end
end

Nesse caso, os templates serão buscados em app/views/notifications, com o nome another. Também é possível especificar um array de caminhos, que serão verificados em ordem.

Se quiser mais flexibilidade, você pode fornecer um bloco e renderizar templates específicos, ou até mesmo renderizar texto ou conteúdo inline sem usar um arquivo de template:

class UserMailer < ApplicationMailer
  default from: '[email protected]'

  def welcome_email
    @user = params[:user]
    @url  = 'http://example.com/login'
    mail(to: @user.email,
         subject: 'Bem vindo ao meu site!') do |format|
      format.html { render 'another_template' }
      format.text { render plain: 'Renderizar texto simples' }
    end
  end
end

Isso fará com que o template 'another_template.html.erb' seja renderizado para a parte HTML, e usará o texto especificado para a parte textual. O comando render é o mesmo usado em Action Controller, então é possível usar as mesmas opções, como por exemplo, :text, :inline, etc.

Se deseja renderizar um template que está fora do diretório padrão app/views/mailer_name/, você pode usar a opção prepend_view_path, da seguinte forma:

class UserMailer < ApplicationMailer
  prepend_view_path "custom/path/to/mailer/view"

  # Isso tentará carregar o template "custom/path/to/mailer/view/welcome_email"
  def welcome_email
    # ...
  end
end

Considere também usar o método append_view_path.

2.4.1 Criando cache de uma view de mailer

É possível criar cache de um fragmento das views de um mailer da mesma forma como fazemos para as views da aplicação, usando o método cache.

<% cache do %>
  <%= @company.name %>
<% end %>

Para usar essa funcionalidade, é necessário configurar sua aplicação da seguinte forma:

config.action_mailer.perform_caching = true

Também é possível criar cache de fragmentos para os emails multipart. Leia mais sobre cache em Guia de cache do Rails.

2.5 Layouts de Action Mailer

Similarmente como nas views dos controllers, é possível também ter layouts para os mailers. O nome do layout deve ser o mesmo do mailer, como user_mailer.html.erb e user_mailer.text.erb para ser reconhecido automaticamente pelo seu mailer como um layout.

Se quiser usar um arquivo diferente, chame layout em seu mailer:

class UserMailer < ApplicationMailer
  layout 'awesome' # use awesome.(html|text).erb as the layout
end

Assim como nas views de controller, use yield para renderizar a view dentro do layout.

Você também pode passar layout: 'layout_name' dentro do bloco de formatação como opção na chamada do render para especificar quais formatos usar em layouts diferentes:

class UserMailer < ApplicationMailer
  def welcome_email
    mail(to: params[:user].email) do |format|
      format.html { render layout: 'my_layout' }
      format.text
    end
  end
end

Vai renderizar a parte HTML usando o arquivo my_layout.html.erb e a parte de texto com o arquivo usual user_mailer.text.erb se ele existir.

2.6 Pré-visualizando Emails

O Action Mailer Preview possibilita uma maneira de pré-visualizar como o email vai ficar, acessando uma URL especial que o renderiza. No exemplo acima, a classe para pré-visualizar UserMailer deve se chamar UserMailerPreview e deve estar localizada em test/mailers/previews/user_mailer_preview.rb. Para ver o modelo de welcome_email, implemente um método que tem o mesmo nome e chame por UserMailer.welcome_email:

class UserMailerPreview < ActionMailer::Preview
  def welcome_email
    UserMailer.with(user: User.first).welcome_email
  end
end

Dessa maneira, o modelo vai ficar disponível em http://localhost:3000/rails/mailers/user_mailer/welcome_email.

Se você mudar algo em app/views/user_mailer/welcome_email.html.erb ou no próprio mailer, ele será automaticamente recarregado e renderizado, para que você veja as mudanças instantaneamente. Uma lista das pré-visualizações também ficam disponíveis em http://localhost:3000/rails/mailers.

Por padrão, essas classes de pré-visualizações ficam em test/mailers/previews. Isso pode ser configurado usando a opção preview_path. Por exemplo, se você quiser alterar para lib/mailer_previews, você pode configurar isso em config/application.rb:

config.action_mailer.preview_path = "#{Rails.root}/lib/mailer_previews"

2.7 Gerando URLs no Action Mailer Views

Ao contrário dos controllers, a instância do mailer não tem nenhum contexto sobre a requisição recebida, então você precisará informar o parâmetro :host.

Como o :host normalmente é o mesmo em toda a aplicação, você pode configurá-lo globalmente no arquivo config/application.rb:

config.action_mailer.default_url_options = { host: 'exemplo.com' }

Por causa dessa característica, você não pode usar nenhum dos helpers *_path dentro de um email. Ao invés, você precisará usar o *_url helper respectivo. Por exemplo, ao invés de usar:

<%= link_to 'welcome', welcome_path %>

Você precisará usar:

<%= link_to 'welcome', welcome_url %>

Usando a URL completa, seus links irão funcionar dentro dos seus emails.

2.7.1 Gerando URLs com `url_for`

Por padrão, o url_for gera uma URL completa nos templates.

Se você não configurar a opção :host globalmente, não esqueça de passá-lo para o url_for.

<%= url_for(host: 'example.com',
            controller: 'welcome',
            action: 'greeting') %>

2.7.2 Gerando URLs com Rotas Nomeadas

Os clientes de email não têm o contexto da web e, portanto, os caminhos não têm a URL base para completar os endereços da web. Assim, você deve sempre usar a variant *_url do helper da rota nomeada.

Se você não configurar a opção :host globalmente, não esqueça de passá-lo para o helper da URL.

<%= user_url(@user, host: 'example.com') %>

Links que não são GET vão exigir o uso de rails-ujs ou jQuery UJS, e, portanto, não irão funcionar em templates de email. Eles irão resultar em requisições GET normais.

2.8 Adicionando Imagens no Action Mailer Views

Ao contrário dos controllers, a instância do mailer não tem nenhum contexto sobre a requisição recebida, então você precisará informar o parâmetro :asset_host.

Como o :asset_host normalmente é o mesmo em toda a aplicação, você pode configurá-lo globalmente no arquivo config/application.rb:

config.asset_host = 'http://example.com'

Agora você pode exibir uma imagem dentro do seu email.

<%= image_tag 'image.jpg' %>

2.9 Enviando Emails Multipart

O Action Mailer enviará automaticamente emails multipart se você tiver templates diferentes para a mesma action. Então, para o nosso exemplo do UserMailer, se você tiver os templates welcome_email.text.erb e welcome_email.html.erb na pasta app/views/user_mailer, o Action Mailer irá automaticamente enviar um email multipart com as versões de HTML e texto configuradas como partes diferentes.

A ordem das partes sendo inseridas é determinado pelo argumento :parts_order dentro do método the ActionMailer::Base.default.

2.10 Enviando Emails com Opções de Entrega Dinâmicas

Se você deseja sobrescrever as opções de entrega padrões (ex: as credenciais SMTP) enquanto o email está sendo enviado, você pode fazer isso usando o delivery_method_options na action do mailer.

class UserMailer < ApplicationMailer
  def welcome_email
    @user = params[:user]
    @url  = user_url(@user)
    delivery_options = { user_name: params[:company].smtp_user,
                         password: params[:company].smtp_password,
                         address: params[:company].smtp_host }
    mail(to: @user.email,
         subject: "Please see the Terms and Conditions attached",
         delivery_method_options: delivery_options)
  end
end

2.11 Enviando Emails sem Renderizar um Template

Podem haver casos onde você quer pular a etapa de renderização de um template e enviar o corpo do email como string. Você pode fazer isso usando a opção :body. Nesses casos, não esqueça de adicionar também a opção :content_type. Caso contrário, o Rails vai usar o text/plain como padrão.

class UserMailer < ApplicationMailer
  def welcome_email
    mail(to: params[:user].email,
         body: params[:email_body],
         content_type: "text/html",
         subject: "Already rendered!")
  end
end

3 Callbacks do Action Mailer

Action Mailer permite que você especifique o before_action, after_action e around_action.

Filtros podem ser especificados com um bloco ou um symbol para um método no Mailer, similar a um controller
Você pode usar um before_action para definir variáveis de instância, popule o objeto de email com valores padrões, ou insira headers e anexos padrões.

class InvitationsMailer < ApplicationMailer
  before_action :set_inviter_and_invitee
  before_action { @account = params[:inviter].account }

  default to:       -> { @invitee.email_address },
          from:     -> { common_address(@inviter) },
          reply_to: -> { @inviter.email_address_with_name }

  def account_invitation
    mail subject: "#{@inviter.name} invited you to their Basecamp (#{@account.name})"
  end

  def project_invitation
    @project    = params[:project]
    @summarizer = ProjectInvitationSummarizer.new(@project.bucket)

    mail subject: "#{@inviter.name.familiar} added you to a project in Basecamp (#{@account.name})"
  end

  private
    def set_inviter_and_invitee
      @inviter = params[:inviter]
      @invitee = params[:invitee]
    end
end

Você pode usar um after_action para fazer uma configuração semelhante ao before_action, mas usando variáveis de instância definidas em sua action do mailer.
Usando um after_action também vai te permitir sobreescrever o método de entrega definido por atualizar mail.delivery_method.settings.

class UserMailer < ApplicationMailer
  before_action { @business, @user = params[:business], params[:user] }

  after_action :set_delivery_options,
               :prevent_delivery_to_guests,
               :set_business_headers

  def feedback_message
  end

  def campaign_message
  end

  private

    def set_delivery_options
      # You have access to the mail instance,
      # @business and @user instance variables here
      if @business && @business.has_smtp_settings?
        mail.delivery_method.settings.merge!(@business.smtp_settings)
      end
    end

    def prevent_delivery_to_guests
      if @user && @user.guest?
        mail.perform_deliveries = false
      end
    end

    def set_business_headers
      if @business
        headers["X-SMTPAPI-CATEGORY"] = @business.code
      end
    end
end

Os filtros do mailer interrompem o processamento adicional se o body estiver definido com um valor não nulo.

4 Usando os helpers do Action Mailer

O Action Mailer agora herda de AbstractController, para que você tenha acesso aos mesmos helpers genéricos que um Action Controller.

Existem também alguns métodos auxiliares específicos do Action Mailer disponíveis em ActionMailer::MailHelper. Por exemplo, estes permitem acessar a instância de mailer a partir da view com mailer, e acessando a mensagem usando message:

<%= stylesheet_link_tag mailer.name.underscore %>
<h1><%= message.subject %></h1>

5 Configuração do Action Mailer

As seguintes opções de configuração são feitas melhor em um dos ambientes arquivos (environment.rb, production.rb, etc...)

Configuração	Descrição
`logger`	Gera informações sobre a execução de correspondência, se disponível. Pode ser definido como `nil` para nenhum registro. Compatível com os loggers `Logger` e `Log4r` do Ruby.
`smtp_settings`	Permite configuração detalhada para o método de entrega `:smtp`: `:address` - Permite que você use um servidor de e-mail remoto. Basta alterar a configuração do padrão `"localhost"`. `:port` - Na chance de seu servidor de e-mail não funcionar na porta 25, você pode alterá-lo. `:domain` - Se você precisar especificar um domínio HELO, pode fazê-lo aqui. `:user_name` - Se o seu servidor de e-mail requer autenticação, defina o nome de usuário neste configuração. `:password` - Se o seu servidor de e-mail requer autenticação, defina a senha neste configuração. `:authentication` - Se o seu servidor de e-mail requer autenticação, você precisa especificar o tipo de autenticação aqui. Este é um símbolo e um dos `:plain` (irá enviar a senha em claro), `:login` (irá enviar senha codificada em Base64) or `:cram_md5` (combina um mecanismo de desafio / resposta para trocar informações e um algoritmo criptográfico Message Digest 5 para hash informações importantes) `:enable_starttls` - Usa STARTTLS quando estiver se conectando com um servidor SMTP e falha se não for suportado. O padrão é `false` `:enable_starttls_auto` - Detecta se STARTTLS está habilitado em seu servidor SMTP e começa a usá-lo. O padrão é `true`. `:openssl_verify_mode` - Ao usar TLS, você pode definir como o OpenSSL verifica o certificado. Isso é realmente útil se você precisar validar um certificado auto assinado e / ou curinga. Você pode usar o nome de uma constante de verificação OpenSSL ('none' ou 'peer') ou diretamente a constante (`OpenSSL::SSL::VERIFY_NONE` ou `OpenSSL::SSL::VERIFY_PEER`). `:ssl/:tls` - Permite que a conexão SMTP use SMTP / TLS (SMTPS: SMTP sobre conexão TLS direta) `:open_timeout` - Número de segundos para esperar ao tentar abrir uma conexão. `:read_timeout` - Número de segundos para esperar até o tempo limite de uma leitura(2) da chamada.
`sendmail_settings`	Permite que você substitua as opções do método de entrega `: sendmail`. `:location` - A localização do executável sendmail. Padrões para `/usr/sbin/sendmail`. `:arguments` - Os argumentos da linha de comando a serem passados ao sendmail. Padrões para `-i`.
`raise_delivery_errors`	Se erros devem ou não ser levantados se o e-mail não for entregue. This only works if the external email server is configured for immediate delivery.
`delivery_method`	Define um método de entrega. Os valores possíveis são: `:smtp` (padrão), pode ser configurado usando `config.action_mailer.smtp_settings`. `:sendmail`, pode ser configurado usando `config.action_mailer.sendmail_settings`. `:file`: salva e-mails em arquivos; pode ser configurado usando `config.action_mailer.file_settings`. `:test`: salvar e-mails para `ActionMailer::Base.deliveries` array. VejaAPI docs para mais informações.
`perform_deliveries`	Determina se as entregas são realmente realizadas quando o método `entrega` é invocado na mensagem do Mail. Por padrão, eles são, mas isso pode ser desligado para ajudar nos testes funcionais. Se este valor for `false`, o array `deliveries` não será preenchido, mesmo se `delivery_method` for `:test`.
`deliveries`	Mantém um array de todos os emails enviados através do Action Mailer com delivery_method: test. Muito útil para testes de unidade e funcional.
`delivery_job`	A classe usada com `deliver_later`. O padrão é `ActionMailer::MailDeliveryJob`.
`deliver_later_queue_name`	O nome da fila usada com `deliver_later`.
`default_options`	Permite definir valores padrão para as opções do método `mail` (`:from`, `:reply_to`, etc.).

Para uma descrição completa das configurações possíveis, consulte o Configuring Action Mailer dentro do nosso guia de configuração de aplicativos Rails.

5.1 Exemplo de configuração do Action Mailer

Um exemplo seria adicionar o seguinte ao seu arquivo config/environments/$RAILS_ENV.rb:

config.action_mailer.delivery_method = :sendmail
# Defaults to:
# config.action_mailer.sendmail_settings = {
#   location: '/usr/sbin/sendmail',
#   arguments: '-i'
# }
config.action_mailer.perform_deliveries = true
config.action_mailer.raise_delivery_errors = true
config.action_mailer.default_options = {from: '[email protected]'}

5.2 Configuração do Action Mailer para Gmail

O Action Mailer agora usa a gem Mail, e aceita configuração semelhante. Adicione isso ao seu arquivo config/environments/$RAILS_ENV.rb para enviar via Gmail:

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address:              'smtp.gmail.com',
  port:                 587,
  domain:               'example.com',
  user_name:            '<username>',
  password:             '<password>',
  authentication:       'plain',
  enable_starttls_auto: true,
  open_timeout:         5,
  read_timeout:         5 }

Em 15 de julho de 2014, o Google aumentou suas medidas de segurança para bloquer as tentativas de aplicativos que considera menos seguros. Você pode alterar suas configurações do Gmail aqui para permitir as tentativas. Se sua conta do Gmail tiver a autenticação de dois fatores ativada em seguida, você precisará definir uma senha de aplicativo e usá-la em vez de sua senha normal.

6 Testes de Mailer

Você encontrará instruções detalhadas de como testar seus mailers no guia de teste.

7 Interceptando e Observando Emails

Action Mailer fornece ganchos para os métodos observador e interceptor do Mail. Eles permitem que você registre classes que são chamadas durante o ciclo de vida de entrega de cada e-mail enviado.

7.1 Interceptando Emails

Os interceptores permitem que você faça modificações em emails antes que eles sejam entregues aos agentes de entrega. Uma classe de interceptor deve implementar o método ::delivering_email(message) que será chamado antes do e-mail ser enviado.

class SandboxEmailInterceptor
  def self.delivering_email(message)
    message.to = ['[email protected]']
  end
end

Antes que o interceptor possa fazer seu trabalho, você precisa registrá-lo usando a configuração interceptor. Você pode fazer isso em um arquivo inicializador como config/initializers/mail_interceptors.rb:

Rails.application.configure do
  if Rails.env.staging?
    config.action_mailer.interceptors = %w[SandboxEmailInterceptor]
  end
end

O exemplo acima usa um ambiente personalizado chamado "staging" para um servidor como em produção, mas para fins de teste. Você pode ler Criação de Ambientes Rails para mais informações sobre ambientes Rails personalizados.

7.2 Observando Emails

Os observadores fornecem acesso à mensagem de e-mail após ela ter sido enviada. Uma classe de observador deve implementar o método :delivered_email(message), que será chamado após o e-mail ser enviado.

class EmailDeliveryObserver
  def self.delivered_email(message)
    EmailDelivery.log(message)
  end
end

Como os interceptores, você precisa registrar observadores usando observers. Você pode fazer isso em um arquivo inicializador como config/initializers/mail_observers.rb

Rails.application.configure do
  config.action_mailer.observers = %w[EmailDeliveryObserver]
end

Feedback

Você é incentivado a ajudar a melhorar a qualidade deste guia.

Por favor, contribua caso veja quaisquer erros, inclusive erros de digitação. Para começar, você pode ler nossa sessão de contribuindo com a documentação.

Você também pode encontrar conteúdo incompleto ou coisas que não estão atualizadas. Por favor, adicione qualquer documentação em falta na main do Rails. Certifique-se de checar o Edge Guides (en-US) primeiro para verificar se o problema já foi resolvido ou não no branch main. Verifique as Diretrizes do Guia Ruby on Rails para estilo e convenções.

Se, por qualquer motivo, você encontrar algo para consertar, mas não conseguir consertá-lo, por favor abra uma issue no nosso Guia.

E por último, mas não menos importante, qualquer tipo de discussão sobre a documentação do Ruby on Rails é muito bem vinda na forum oficial do Ruby on Rails e nas issues do Guia em português.

Guiarails.com.br

Chapters