ActionMailbox Migration Guide

ActionMailbox Migration Guide

This guide explains how to migrate from the legacy script/mailin or POP polling ingestion to Rails ActionMailbox for handling incoming email in Alaveteli.

Overview

ActionMailbox replaces the legacy email ingestion methods:

• Old: script/mailin script or POP poller
• New: Rails ActionMailbox using RequestMailbox#process

The routing logic that used to live in RequestMailer#receive should be moved to RequestMailbox#process in app/mailboxes/request_mailbox.rb.

Migration steps

1. Remove the old ingestion

   • Stop the POP poller systemd service (if you have one).
   • Remove references to script/mailin from your mail server configuration.

2. Set credentials

   • Add a strong action_mailbox.ingress_password to your Rails credentials.

3. Configure ActionMailbox ingestion

   • Choose an ingress method: MTA relay pipe (Postfix/Exim/Qmail) or a third‑party webhook service (SendGrid, Postmark, Mailgun, Mandrill).

Set credentials

Edit credentials:

bin/rails credentials:edit

Add the following (replace with a strong random password):

action_mailbox:
  ingress_password: "strong-random-password"

Note: After editing credentials, back up config/master.key if you haven't already. This file is generated automatically and is the private encryption key for the credentials. Without it the application cannot read the credentials; you will need it if you move servers or reinstall Alaveteli.

MTA relay configuration (Postfix, Exim, Qmail)

ActionMailbox supports Postfix, Exim and Qmail as MTA relays. Most Alaveteli installs use Postfix; the steps below show the Postfix example and are similar for other MTAs.

In /etc/postfix/master.cf, find the script/mailin ingestion line similar to:

# script/mailin ingestion
alaveteli unix  -       n       n       -       -       pipe flags=R user=alaveteli argv=/path/to/alaveteli/script/mailin

Update it to call the ActionMailbox ingress command. For Postfix use:

# ActionMailbox ingestion
alaveteli unix  -       n       n       -       -       pipe flags=R user=alaveteli argv=/path/to/alaveteli/bin/rails action_mailbox:ingress:postfix URL=https://example.com/rails/action_mailbox/postfix/inbound_emails INGRESS_PASSWORD=your_ingress_password

Make sure you set:

• The correct path to your Alaveteli install (/path/to/alaveteli).
• The correct domain/name in the URL.
• INGRESS_PASSWORD to the password you configured in credentials.

For Exim or Qmail, switch the rake task to action_mailbox:ingress:exim or action_mailbox:ingress:qmail respectively.

Reload Postfix after making the change:

postmap /etc/postfix/virtual
postfix reload

Third‑party services (SendGrid, Postmark, Mailgun, Mandrill)

If you prefer not to run your own mail server, you can use a hosted email provider that can forward inbound messages to your application via webhooks.

1. Configure Alaveteli to use the chosen retriever method by setting it in config/general.yml:

PRODUCTION_MAILER_RETRIEVER_METHOD: sendgrid # or postmark, mailgun, mandrill

2. Configure the webhook in your third‑party service

Set the destination (webhook) URL in the provider to your ActionMailbox ingress endpoint. For example:

https://actionmailbox:INGRESS_PASSWORD@example.com/rails/action_mailbox/sendgrid/inbound_emails

Note: The exact way to supply the ingress password depends on the provider. Some providers support HTTP basic auth in the URL (as shown above), others allow you to set a secret header or query parameter. Follow the provider's documentation and the Rails ActionMailbox docs for details on how to authenticate webhooks.

Additional resources

See the Rails ActionMailbox guide for detailed configuration for each service:

https://guides.rubyonrails.org/action_mailbox_basics.html

Testing ingestion locally

You can test ingestion from the command line by piping an email into ActionMailbox:

# Via stdin
cat spec/fixtures/files/incoming-request-plain.eml | \
  bin/rails runner 'ActionMailbox::IncomingEmail.create_and_extract_message_id!($stdin.read)'