Conceptos básicos de Action Mailbox

Chapters

1. ¿Qué es Action Mailbox?
2. Configuración
3. Configuración(duplicated)
   • Exim
   • Mailgun
   • Mandrill
   • Postfix
   • Postmark
   • Qmail
   • SendGrid
4. Ejemplos
5. Incineración de InboundEmails
6. Trabajando con Action Mailbox en desarrollo
7. Pruebas de buzones

1 ¿Qué es Action Mailbox?

Action Mailbox enruta correos electrónicos entrantes a buzones similares a controladores para su procesamiento en Rails. Viene con ingresos para Mailgun, Mandrill, Postmark y SendGrid. También puedes manejar correos entrantes directamente a través de los ingresos integrados de Exim, Postfix y Qmail.

Los correos electrónicos entrantes se convierten en registros de InboundEmail utilizando Active Record y cuentan con seguimiento del ciclo de vida, almacenamiento del correo electrónico original en almacenamiento en la nube a través de Active Storage y manejo responsable de datos con incineración activada por defecto.

Estos correos electrónicos entrantes se enrutan de forma asíncrona utilizando Active Job a uno o varios buzones dedicados, que son capaces de interactuar directamente con el resto de tu modelo de dominio.

2 Configuración

Instala las migraciones necesarias para InboundEmail y asegúrate de que Active Storage esté configurado:

$ bin/rails action_mailbox:install
$ bin/rails db:migrate

3 Configuración(duplicated)

3.1 Exim

Indica a Action Mailbox que acepte correos electrónicos de un retransmisor SMTP:

# config/environments/production.rb
config.action_mailbox.ingress = :relay

Genera una contraseña segura que Action Mailbox pueda usar para autenticar las solicitudes al ingreso de retransmisión.

Usa bin/rails credentials:edit para agregar la contraseña a las credenciales cifradas de tu aplicación en action_mailbox.ingress_password, donde Action Mailbox la encontrará automáticamente:

action_mailbox:
  ingress_password: ...

Alternativamente, proporciona la contraseña en la variable de entorno RAILS_INBOUND_EMAIL_PASSWORD.

Configura Exim para que envíe correos electrónicos entrantes a bin/rails action_mailbox:ingress:exim, proporcionando la URL del ingreso de retransmisión y la INGRESS_PASSWORD que generaste anteriormente. Si tu aplicación viviera en https://example.com, el comando completo se vería así:

$ bin/rails action_mailbox:ingress:exim URL=https://example.com/rails/action_mailbox/relay/inbound_emails INGRESS_PASSWORD=...

3.2 Mailgun

Proporciona a Action Mailbox tu clave de firma de Mailgun (que puedes encontrar en Configuración -> Seguridad y usuarios -> Seguridad de API en Mailgun), para que pueda autenticar las solicitudes al ingreso de Mailgun.

Usa bin/rails credentials:edit para agregar tu clave de firma a las credenciales cifradas de tu aplicación en action_mailbox.mailgun_signing_key, donde Action Mailbox la encontrará automáticamente:

action_mailbox:
  mailgun_signing_key: ...

Alternativamente, proporciona tu clave de firma en la variable de entorno MAILGUN_INGRESS_SIGNING_KEY.

Indica a Action Mailbox que acepte correos electrónicos de Mailgun:

# config/environments/production.rb
config.action_mailbox.ingress = :mailgun

Configura Mailgun para que reenvíe correos electrónicos entrantes a /rails/action_mailbox/mailgun/inbound_emails/mime. Si tu aplicación viviera en https://example.com, especificarías la URL completamente calificada https://example.com/rails/action_mailbox/mailgun/inbound_emails/mime.

3.3 Mandrill

Proporciona a Action Mailbox tu clave de API de Mandrill, para que pueda autenticar las solicitudes al ingreso de Mandrill.

Usa bin/rails credentials:edit para agregar tu clave de API a las credenciales cifradas de tu aplicación en action_mailbox.mandrill_api_key, donde Action Mailbox la encontrará automáticamente:

action_mailbox:
  mandrill_api_key: ...

Alternativamente, proporciona tu clave de API en la variable de entorno MANDRILL_INGRESS_API_KEY.

Indica a Action Mailbox que acepte correos electrónicos de Mandrill:

# config/environments/production.rb
config.action_mailbox.ingress = :mandrill

Configura Mandrill para que enrute correos electrónicos entrantes a /rails/action_mailbox/mandrill/inbound_emails. Si tu aplicación viviera en https://example.com, especificarías la URL completamente calificada https://example.com/rails/action_mailbox/mandrill/inbound_emails.

3.4 Postfix

Indica a Action Mailbox que acepte correos electrónicos de un retransmisor SMTP:

# config/environments/production.rb
config.action_mailbox.ingress = :relay

Genera una contraseña segura que Action Mailbox pueda usar para autenticar las solicitudes al ingreso de retransmisión.

Usa bin/rails credentials:edit para agregar la contraseña a las credenciales cifradas de tu aplicación en action_mailbox.ingress_password, donde Action Mailbox la encontrará automáticamente:

action_mailbox:
  ingress_password: ...

Alternativamente, proporciona la contraseña en la variable de entorno RAILS_INBOUND_EMAIL_PASSWORD.

Configura Postfix para que envíe correos electrónicos entrantes a bin/rails action_mailbox:ingress:postfix, proporcionando la URL del ingreso de Postfix y la INGRESS_PASSWORD que generaste anteriormente. Si tu aplicación viviera en https://example.com, el comando completo se vería así:

$ bin/rails action_mailbox:ingress:postfix URL=https://example.com/rails/action_mailbox/relay/inbound_emails INGRESS_PASSWORD=...

3.5 Postmark

Indica a Action Mailbox que acepte correos electrónicos de Postmark:

# config/environments/production.rb
config.action_mailbox.ingress = :postmark

Genera una contraseña segura que Action Mailbox pueda usar para autenticar las solicitudes al ingreso de Postmark.

Usa bin/rails credentials:edit para agregar la contraseña a las credenciales cifradas de tu aplicación en action_mailbox.ingress_password, donde Action Mailbox la encontrará automáticamente:

action_mailbox:
  ingress_password: ...

Alternativamente, proporciona la contraseña en la variable de entorno RAILS_INBOUND_EMAIL_PASSWORD.

Configura el webhook de entrada de Postmark para que reenvíe correos electrónicos entrantes a /rails/action_mailbox/postmark/inbound_emails con el nombre de usuario actionmailbox y la contraseña que generaste anteriormente. Si tu aplicación viviera en https://example.com, configurarías Postmark con la siguiente URL completamente calificada: https://actionmailbox:CONTRASEÑ[email protected]/rails/action_mailbox/postmark/inbound_emails

NOTA: Al configurar tu webhook de entrada de Postmark, asegúrate de marcar la casilla que dice "Incluir contenido de correo electrónico sin procesar en la carga útil JSON". Action Mailbox necesita el contenido de correo electrónico sin procesar para funcionar.

3.6 Qmail

Indica a Action Mailbox que acepte correos electrónicos de un retransmisor SMTP:

# config/environments/production.rb
config.action_mailbox.ingress = :relay

Genera una contraseña segura que Action Mailbox pueda usar para autenticar las solicitudes al retransmisor de entrada.

Usa bin/rails credentials:edit para agregar la contraseña a las credenciales cifradas de tu aplicación en action_mailbox.ingress_password, donde Action Mailbox la encontrará automáticamente:

action_mailbox:
  ingress_password: ...

Alternativamente, proporciona la contraseña en la variable de entorno RAILS_INBOUND_EMAIL_PASSWORD.

Configura Qmail para redirigir los correos electrónicos entrantes a bin/rails action_mailbox:ingress:qmail, proporcionando la URL del retransmisor de entrada y la INGRESS_PASSWORD que generaste anteriormente. Si tu aplicación se encuentra en https://example.com, el comando completo se vería así:

$ bin/rails action_mailbox:ingress:qmail URL=https://example.com/rails/action_mailbox/relay/inbound_emails INGRESS_PASSWORD=...

3.7 SendGrid

Indica a Action Mailbox que acepte correos electrónicos de SendGrid:

# config/environments/production.rb
config.action_mailbox.ingress = :sendgrid

Genera una contraseña segura que Action Mailbox pueda usar para autenticar las solicitudes al retransmisor de SendGrid.

Usa bin/rails credentials:edit para agregar la contraseña a las credenciales cifradas de tu aplicación en action_mailbox.ingress_password, donde Action Mailbox la encontrará automáticamente:

action_mailbox:
  ingress_password: ...

Alternativamente, proporciona la contraseña en la variable de entorno RAILS_INBOUND_EMAIL_PASSWORD.

Configura el análisis de entrada de SendGrid para redirigir los correos electrónicos entrantes a /rails/action_mailbox/sendgrid/inbound_emails con el nombre de usuario actionmailbox y la contraseña que generaste anteriormente. Si tu aplicación se encuentra en https://example.com, configura SendGrid con la siguiente URL:

https://actionmailbox:CONTRASEÑ[email protected]/rails/action_mailbox/sendgrid/inbound_emails

NOTA: Al configurar tu webhook de análisis de entrada de SendGrid, asegúrate de marcar la casilla que dice “Publicar el mensaje MIME completo sin procesar.”. Action Mailbox necesita el mensaje MIME completo sin procesar para funcionar.

4 Ejemplos

Configura enrutamiento básico:

# app/mailboxes/application_mailbox.rb
class ApplicationMailbox < ActionMailbox::Base
  routing(/^save@/i     => :forwards)
  routing(/@replies\./i => :replies)
end

Luego configura un buzón:

# Genera un nuevo buzón
$ bin/rails generate mailbox forwards

# app/mailboxes/forwards_mailbox.rb
class ForwardsMailbox < ApplicationMailbox
  # Los callbacks especifican los requisitos previos para el procesamiento
  before_processing :require_projects

  def process
    # Registra el reenvío en el proyecto correspondiente, o...
    if forwarder.projects.one?
      record_forward
    else
      # ...involucra a un segundo Action Mailer para preguntar en qué proyecto se debe reenviar.
      request_forwarding_project
    end
  end

  private
    def require_projects
      if forwarder.projects.none?
        # Usa Action Mailers para rebotar los correos electrónicos entrantes de vuelta al remitente, esto detiene el procesamiento
        bounce_with Forwards::BounceMailer.no_projects(inbound_email, forwarder: forwarder)
      end
    end

    def record_forward
      forwarder.forwards.create subject: mail.subject, content: mail.content
    end

    def request_forwarding_project
      Forwards::RoutingMailer.choose_project(inbound_email, forwarder: forwarder).deliver_now
    end

    def forwarder
      @forwarder ||= User.find_by(email_address: mail.from)
    end
end

5 Incineración de InboundEmails

Por defecto, un InboundEmail que ha sido procesado correctamente se incinerará después de 30 días. Esto asegura que no estés conservando los datos de las personas sin motivo después de que hayan cancelado sus cuentas o eliminado su contenido. La intención es que después de procesar un correo electrónico, hayas extraído todos los datos necesarios y los hayas convertido en modelos de dominio y contenido en tu lado de la aplicación. El InboundEmail simplemente permanece en el sistema durante un tiempo adicional para proporcionar opciones de depuración y forenses.

La incineración real se realiza a través del IncinerationJob que está programado para ejecutarse después de config.action_mailbox.incinerate_after. Este valor está configurado de forma predeterminada en 30.days, pero puedes cambiarlo en tu archivo de configuración production.rb. (Ten en cuenta que esta programación de incineración a largo plazo depende de que tu cola de trabajos pueda mantener los trabajos durante ese tiempo).

6 Trabajando con Action Mailbox en desarrollo

Es útil poder probar correos electrónicos entrantes en desarrollo sin enviar ni recibir correos electrónicos reales. Para lograr esto, hay un controlador conductor montado en /rails/conductor/action_mailbox/inbound_emails, que te proporciona un índice de todos los InboundEmails en el sistema, su estado de procesamiento y un formulario para crear un nuevo InboundEmail también.

7 Pruebas de buzones

Ejemplo:

class ForwardsMailboxTest < ActionMailbox::TestCase
  test "grabar directamente un reenvío de cliente para un remitente y destinatario correspondientes a un proyecto" do
    assert_difference -> { people(:david).buckets.first.recordings.count } do
      receive_inbound_email_from_mail \
        to: '[email protected]',
        from: people(:david).email_address,
        subject: "Fwd: Actualización de estado?",
        body: <<~BODY
          --- Begin forwarded message ---
          From: Frank Holland <[email protected]>

          ¿Cuál es el estado?
        BODY
    end

    recording = people(:david).buckets.first.recordings.last
    assert_equal people(:david), recording.creator
    assert_equal "Actualización de estado?", recording.forward.subject
    assert_match "¿Cuál es el estado?", recording.forward.content.to_s
  end
end

Consulta la API de ActionMailbox::TestHelper para obtener más métodos de ayuda para pruebas. ```

Comentarios

Se te anima a ayudar a mejorar la calidad de esta guía.

Por favor, contribuye si encuentras algún error tipográfico o factual. Para empezar, puedes leer nuestra contribución a la documentación sección.

También puedes encontrar contenido incompleto o desactualizado. Por favor, añade cualquier documentación faltante para main. Asegúrate de revisar Edge Guides primero para verificar si los problemas ya están resueltos o no en la rama principal. Consulta las Directrices de las Guías de Ruby on Rails para el estilo y las convenciones.

Si por alguna razón encuentras algo que corregir pero no puedes solucionarlo tú mismo, por favor abre un problema.

Y por último, cualquier tipo de discusión sobre la documentación de Ruby on Rails es muy bienvenida en el Foro oficial de Ruby on Rails.