= postmark-rails gem

{<img src="https://travis-ci.org/wildbit/postmark-rails.png?branch=master" alt="Build Status" />}[https://travis-ci.org/wildbit/postmark-rails] {<img src="https://codeclimate.com/github/wildbit/postmark-rails.png" />}[https://codeclimate.com/github/wildbit/postmark-rails]

The Postmark Rails Gem is a drop-in plug-in for ActionMailer to send emails via Postmark, an email delivery service for web apps. The gem has been created for fast implementation and fully supports all of Postmark’s features.

== Supported Rails Versions

* lower than 2.3: could work, but not tested
* 2.3 and higher
* 3.0
* 4.0

== Install

    sudo gem install postmark-rails

== Requirements

* "postmark" gem version 0.9 and higher is required.
* You will also need a Postmark account, server and sender signature set up to use it. To get an account, sign up at http://postmarkapp.com.

== Configuring your Rails application

=== Rails 3

Add this to your Gemfile: (change version numbers if needed)

    gem 'postmark-rails', '0.4.2'

Don't forget to run "bundle install" command every time you change something in the Gemfile.

Add this to your config/application.rb:

    config.action_mailer.delivery_method   = :postmark
    config.action_mailer.postmark_settings = { :api_key => "your-api-key" }

=== Rails 2

Add this to config/environment.rb:

    Rails::Initializer.run do |config|

      ...

      config.gem 'postmark-rails'
      require    'postmark-rails'

      config.action_mailer.postmark_api_key = "your-api-key"
      config.action_mailer.delivery_method  = :postmark

      ...

    end

For API details, refer to the developer documentation at http://developer.postmarkapp.com.

== Tagging your deliveries

You can use a tag to categorize outgoing messages and attach application-specific information. Tagging the different types of email that you send lets you review statistics and bounce reports separately. Read more at http://developer.postmarkapp.com/developer-build.html#message-format.

=== Rails 3

    class TestMailer < ActionMailer::Base

      def tagged_message
        mail(
          :subject => 'hello',
          :to      => 'sheldon@bigbangtheory.com',
          :from    => 'leonard@bigbangtheory.com',
          :tag     => 'my-tag'
        )
      end

    end

=== Rails 2

    class SuperMailer < ActionMailer::Base

      def email
        from       "no-reply@example.com"
        subject    "Some marvelous email message"
        recipients "someone-fancy@example.com"
        tag        "my-another-tag"
      end

    end

== Sending attachments

You can also send file attachments with Postmark. Read our Developer docs for additional information: http://developer.postmarkapp.com/developer-build.html#attachments.

The Postmark gem is compatible with [ActionMailer attachments API](http://api.rubyonrails.org/classes/ActionMailer/Base.html#method-i-attachments).

The legacy #postmark_attachments method is no longer supported on Rails 3.2.13 and above.

=== Rails 3

    class TestMailer < ActionMailer::Base

      def message_with_attachment
        attachment['42.jpg'] = File.read("/path/to/file")
        mail(
          :subject              => 'hello',
          :to                   => 'sheldon@bigbangtheory.com',
          :from                 => 'leonard@bigbangtheory.com'
        )
      end

    end

=== Rails 2

    class SuperMailer < ActionMailer::Base

      def email
        from                 "no-reply@example.com"
        subject              "Some marvelous email message"
        recipients           "someone-fancy@example.com"
        postmark_attachments [File.open("/path/to/file")]
      end

    end

You can pass either an array of File objects or a single object. Postmark will detect the file name automatically and send an attachment with the "application/octet-stream" content type. If you want more control on how attachments get formatted, you can pass Hash objects, which contain the custom settings such as file name or content-type. Here is an example:

    #
    # Don't forget to read your file and base64-encode it,
    # before assigning it to "Content".
    #
    message.postmark_attachments = {
      "Name"        => "fancy-file-name.jpg",
      "Content"     => [ IO.read("path/to/file") ].pack("m"),
      "ContentType" => "image/jpeg"
    }

== Note on Patches/Pull Requests

* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so we don’t break it in a future version unintentionally.
* Commit, do not mess with rakefile, version, or history.
* Send a pull request. Bonus points for topic branches.

== Authors & Contributors

* Artem Chistyakov
* Petyo Ivanov
* Ilya Sabanin
* Hristo Deshev
* Randy Schmidt
* Chris Williams
* Nicolás Sanguinetti
* Laust Rud Jacobsen (rud)

== Copyright

Copyright © 2010 Wildbit LLC. See LICENSE for details.