Installation

The PostageApp gem can be added to any Ruby project and will work with Ruby 2.0 or later.

Ruby applications, including Sinatra and Rack-based ones, are fully supported. Additional features are specifically for Ruby on Rails.

Using with Ruby on Rails

Add the dependency to the application’s Gemfile:

gem 'postageapp'

Then from the Rails project’s root run:

bundle install
bin/rails generate postageapp --api-key PROJECT_API_KEY

NOTE: Replace PROJECT_API_KEY with the API key from your PostageApp project.

Sinatra / Rack / Others

You’ll need to install the gem first:

$ sudo gem install postageapp

And then it’s as simple as doing something like this:

require 'postageapp'

PostageApp.configure do |config|
  config.api_key = 'PROJECT_API_KEY'
end

NOTE: Replace PROJECT_API_KEY with the API key from your PostageApp project.

Usage

Here’s an example of sending a message (See full API documentation):

request = PostageApp::Request.new(:send_message, {
  'headers'     => { 'from'     => 'sender@example.com',
                     'subject'  => 'Email Subject' },
  'recipients'  => 'recipient@example.com',
  'content'     => {
    'text/plain'  => 'text email content',
    'text/html'   => 'html email content'
  }
})
response = request.send

PostageApp::Response object allows you to check the status:

>> response.status
=> 'ok'

Alternatively you may use:

>> response.fail?
=> false
>> response.ok?
=> true

Response usually comes back with data:

>> response.data
=> { 'message' => { 'id' => '12345' }}

Recipient Override

Sometimes you don’t want to send emails to real people in your application. For that there’s an ability to override to what address all emails will be delivered. All you need to do is modify configuration block like this (in Rails projects it’s usually found in RAILS_ROOT/config/initializers/postageapp.rb):

PostageApp.configure do |config|
  config.api_key            = 'PROJECT_API_KEY'
  config.recipient_override = 'you@example.com' unless Rails.env.production?
end

ActionMailer Integration

You can quickly convert your existing mailers to use PostageApp service by simply changing class MyMailer < ActionMailer::Base to class MyMailer < PostageApp::Mailer. If you using ActionMailer from outside of Rails make sure you have this line somewhere: require 'postageapp/mailer'

There are custom methods that allow setting of template and variables parts of the API call. They are postageapp_template and postageapp_variables. Examples how they are used are below. For details what they do please see documentation

Ruby on Rails

Here’s an example of a mailer in the Rails environment:

require 'postageapp/mailer'

class Notifier < PostageApp::Mailer
  def signup_notification
    # PostageApp specific elements:
    postageapp_template 'sample_child_template'
    postageapp_variables 'global_variable' => 'value'

    # Add attachments as necessary, uncomment the example below
    # attachments['example.zip'] = File.read('/path/to/example.zip')

    # Add custom headers if necessary
    # headers['Special-Header'] = 'SpecialValue'

    mail(
      from: 'test@example.com', # Replace with your Sender
      subject: 'Test Message',
      to: {
        'recipient_1@example.com' => { 'variable' => 'value' },
        'recipient_2@example.com' => { 'variable' => 'value' }
      }
    )
  end
end

This can be tested using the Rails console (bin/rails c):

Notifier.signup_notification.deliver_now

Unless you’ve changed the recipients this messsage will be rejected as a test so it won’t be delivered.

API of previous ActionMailer is partially supported under Rails 3 environment. Please note that it’s not 100% integrated, some methods/syntax will not work. You may still define you mailers in this way (but really shouldn’t):

require 'postageapp/mailer'

class Notifier < PostageApp::Mailer

  def signup_notification
    from        'sender@example.com'
    subject     'Test Email'
    recipients  'recipient@example.com'
  end
end

Automatic resending in case of failure

For those rare occasions when the PostageApp API is not reachable this gem will buffer unsent requests and then attempts to resend them after the next successful API call. In Rails environment it will create a folder: RAILS_ROOT/tmp/postageapp_failed_requests and save all failed requests there. On successful resend file for that request will be deleted.

For projects other than Rails you’ll need to tell where there project_root is located as this can’t be determined automaticallly via Rails.root:

PostageApp.configure do |config|
  config.api_key      = 'PROJECT_API_KEY'
  config.project_root = "/path/to/your/project"
end

Integrating with Devise

Create a custom Postageapp mailer class as follows (you can also copy the default app/mailers/devise/mailer.rb file in the devise library and modify it accordingly):

class MyDeviseMailer < PostageApp::Mailer
  include Devise::Mailers::Helpers

  def confirmation_instructions(record)
    # PostageApp specific elements (example):
    postageapp_template 'my-signup-confirmation'
    postageapp_variables :email => record.email,
                         :link  => confirmation_url(record, :confirmation_token => record.confirmation_token)

    devise_mail(record, :confirmation_instructions)
  end

  def reset_password_instructions(record)
    # PostageApp specific elements (example):
    postageapp_template 'my-password-reset'
    postageapp_variables :name  => record.name ||= record.email,
                         :link  => password_url(record, :reset_password_token => record.reset_password_token)

    devise_mail(record, :reset_password_instructions)
  end

  def unlock_instructions(record)
    # PostageApp specific elements (example):
    postageapp_template 'my-unlock-instructions'
    postageapp_variables :name  => record.name ||= record.email,
                         :link  => unlock_url(record, :unlock_token => record.unlock_token)

    devise_mail(record, :unlock_instructions)
  end
end

In the /config/initializers/devise.rb file, set the custom mailer to be:

config.mailer = "MyDeviseMailer"