MailPace::Rails

MailPace lets you send transactional emails from your app over an easy to use API.

The MailPace Rails Gem is a plug in for ActionMailer to send emails via MailPace to make sending emails from Rails apps super simple.

New in 0.3.0: The ability to consume inbound emails from MailPace via ActionMailbox

Usage

Once installed and configured, continue to send emails using ActionMailer and receive emails with ActionMailbox like normal.

Other Requirements

You will need an MailPace account with a verified domain and organization with an active plan.

Installation

Account Setup

Set up an account at MailPace and complete the Onboarding steps

Gem Installation

Add this line to your application's Gemfile:

gem 'mailpace-rails'

And then execute:

$ bundle

Or install it yourself as:

$ gem install mailpace-rails

Configure the Gem

First you will need to retrieve your API token for your sending domain from MailPace. You can find it under Organization -> Domain -> API Tokens.

Use the encrypted secret management to save your API Token to config/credentials.yml.enc by running the following:

rails secret
rails credentials:edit

Then add your token:

mailpace_api_token: "TOKEN_GOES_HERE"

Set MailPace as your mail delivery method in config/application.rb:

config.action_mailer.delivery_method = :mailpace
config.action_mailer.mailpace_settings = { api_token: Rails.application.credentials.mailpace_api_token }

Tagging

You can tag messages and filter them later in the MailPace UI. To do this, pass the tags as a header by adding a tag variable to your mail method call.

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

  def single_tag
    mail(
      tags: 'test tag' # One tag
    )
  end

  def multi_tag
    mail(
      tags: "['test tag', 'another-tag']" # Multiple tags
    )
  end
end

Note that this should always be a string, even if using an array of multiple tags.

List-Unsubscribe

To add a List-Unsubscribe header, pass a list_unsubscribe string to the mail function:

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

  def list_unsub_header
    mail(
      list_unsubscribe: 'https://listunsublink.com'
    )
  end
end

ActionMailbox (for receiving inbound emails)

As of v0.3.0, this Gem supports handling Inbound Emails (see https://docs.mailpace.com/guide/inbound/ for more details) via ActionMailbox. To set this up:

1. Tell Action Mailbox to accept emails from MailPace in config/environments/production.rb

config.action_mailbox.ingress = :mailpace

2. Generate a strong password that Action Mailbox can use to authenticate requests to the MailPace ingress. Use bin/rails credentials:edit to add the password to your application's encrypted credentials under action_mailbox.ingress_password, where Action Mailbox will automatically find it:

action_mailbox:
  ingress_password: ...

Alternatively, provide the password in the RAILS_INBOUND_EMAIL_PASSWORD environment variable.

3. Configure MailPace to forward inbound emails to /rails/action_mailbox/mailpace/inbound_emails with the username actionmailbox and the password you previously generated. If your application lived at https://example.com you would configure your MailPace inbound endpoint URL with the following fully-qualified URL:

https://actionmailbox:[email protected]/rails/action_mailbox/mailpace/inbound_emails

That's it! Emails should start flowing into your app just like magic.

Support

For support please check the MailPace Documentation or contact us at [email protected]

Contributing

Please ensure to add a test for any change you make. To run the tests:

bin/test

Pull requests always welcome

License

The gem is available as open source under the terms of the MIT License.