Skip to content

Commit

Permalink
updated docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@ibalosh
ibalosh committed Nov 7, 2018
1 parent 82028db commit 02b5fe8
Show file tree
Hide file tree
Showing 3 changed files with 43 additions and 196 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Expand Up @@ -8,3 +8,4 @@ pkg
.rvmrc
Gemfile.lock
gemfiles/*.lock
**/*.idea
238 changes: 42 additions & 196 deletions README.md
View file
@@ -1,18 +1,41 @@
# postmark-rails gem
<a href="https://postmarkapp.com">
<img src="postmark.png" alt="Postmark Logo" title="Postmark" width="120" height="120" align="right">
</a>

# Postmark Rails Gem

[![Build Status](https://travis-ci.org/wildbit/postmark-rails.svg?branch=master)](https://travis-ci.org/wildbit/postmark-rails) [![Code Climate](https://codeclimate.com/github/wildbit/postmark-rails/badges/gpa.svg)](https://codeclimate.com/github/wildbit/postmark-rails)
[![License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](http://www.opensource.org/licenses/MIT)
[![Gem Version](https://badge.fury.io/rb/postmark-rails.svg)](https://badge.fury.io/rb/postmark-rails)

[Postmark](https://postmarkapp.com) allows you to send your emails with high delivery rates.
It also includes detailed statistics. In addition, Postmark can parse incoming emails which are forwarded back to your application.

The Postmark Rails Gem is a drop-in plug-in for ActionMailer to send emails via [Postmark](https://postmarkapp.com).
The gem has been created for fast implementation and fully supports all of [Postmark’s features](https://postmarkapp.com/why).

## Usage

Please see the [wiki](https://github.com/wildbit/postmark-rails/wiki) for detailed instructions about library features.
For details about Postmark API in general, please check out [Postmark developer docs](https://postmarkapp.com/developer).

## Requirements

You will need a Postmark account, server and sender signature (or verified domain) set up to use it.
For details about setup, check out [wiki pages](https://github.com/wildbit/postmark-rails/wiki/Getting-Started).

The Postmark Rails Gem is a drop-in plug-in for ActionMailer to send emails via [Postmark](https://postmarkapp.com), an email delivery service for web apps. The gem has been created for fast implementation and fully supports all of [Postmark’s features](https://postmarkapp.com/why).
Also you will need a [postmark gem](https://github.com/wildbit/postmark-gem) version 1.0 and higher is required.

## Supported Rails Versions
### Supported Rails Versions

* Rails 5.0
* Rails 4.x
* Rails 3.x

For Rails 2.3 please take a look at [version 0.4](https://github.com/wildbit/postmark-rails/tree/v0.4.2). It may miss some new features, but receives all required bug fixes and other support if needed.
For Rails 2.3 please take a look at [version 0.4](https://github.com/wildbit/postmark-rails/tree/v0.4.2).
It may miss some new features, but receives all required bug fixes and other support if needed.

## Configuring your Rails application
## Installation

Add `postmark-rails` to your Gemfile and run `bundle install`.

Expand All @@ -35,198 +58,11 @@ config.action_mailer.postmark_settings = { :api_token => Rails.application.secre

**Note**: The `postmark_settings` hash can contain [any options](https://github.com/wildbit/postmark-gem#communicating-with-the-api) supported by `Postmark::ApiClient`.

## Tracking opens and tagging your deliveries

You can use tags 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](http://developer.postmarkapp.com/developer-build.html#message-format).

Pass `:track_opens => 'true'` to enable/disable open tracking on per-message basis. Check out the [Triggers API](https://github.com/wildbit/postmark-gem/wiki/The-Triggers-API-Support) to see how Postmark can help you control this with tags. **Note that we pass a string here, since it becomes a header value. Passing a boolean may or may not work depending on your Rails version.**

``` ruby
class TestMailer < ActionMailer::Base

def tagged_message
mail(
:subject => 'hello',
:to => 'sheldon@bigbangtheory.com',
:from => 'leonard@bigbangtheory.com',
:tag => 'my-tag',
:track_opens => 'true'
)
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). It allows you to specify the name, content-type and other attributes for your attachments.

The legacy `:postmark_attachments` attribute is *no longer supported* on Rails 3.2.13 and above.

``` ruby
class TestMailer < ActionMailer::Base

def message_with_attachment
attachments.inline['logo.png'] = File.read("/path/to/image") # Inline image
attachments['42.jpg'] = File.read("/path/to/file") # Attached file
mail(
:subject => 'hello',
:to => 'sheldon@bigbangtheory.com',
:from => 'leonard@bigbangtheory.com'
)
end

end
```

## Attaching metadata to messages

Postmark supports [attaching metadata to messages](https://postmarkapp.com/support/article/1125-custom-metadata-faq-1). All metadata field values will be interpreted and returned in webhook payloads as strings.

``` ruby
class TestMailer < ActionMailer::Base

def message_with_metadata
metadata['foo'] = 'bar'
mail(
:subject => 'meta hello',
:to => 'sheldon@bigbangtheory.com',
:from => 'leonard@bigbangtheory.com'
)
end

end
```

## Sending in batches

While Postmark is focused on transactional email, we understand that developers
with higher volumes or processing time constraints need to send their messages
in batches. To facilitate this we provide a batching endpoint that permits you
to send up to 500 well-formed Postmark messages in a single API call.

``` ruby
client = Postmark::ApiClient.new('your-api-token')

messages = []
messages << DigestMailer.weekly_digest(@user1)
messages << DigestMailer.weekly_digest(@user2)

client.deliver_messages(messages)

messages.first.delivered?
# => true

messages.all?(&:delivered)
# => true
```

## Error handling

The gem respects the `ActionMailer::Base.raise_delivery_errors` setting and will surpress any exceptions
if it’s set to `false`. When delivery errors are enabled, the gem can raise any one of the exceptions
listed in the [postmark](https://github.com/wildbit/postmark-gem#error-handling) gem docs.


### ActionMailer 5

For ActionMailer 5 and above, use `ActionMailer::Base.rescue_from` to define handlers for
each error you care about.

#### Example

``` ruby
class ApplicationMailer < ActionMailer::Base
default from: 'user@example.org'
layout 'mailer'

rescue_from Postmark::InactiveRecipientError, with: :reactivate_and_retry

private

def postmark_client
::Postmark::ApiClient.new(ActionMailer::Base.postmark_settings[:api_token],
ActionMailer::Base.postmark_settings.except(:api_token))
end


# This is just an example. Sometimes you might not want to reactivate
# an address that hard bounced.
# Warning: Having too many bounces can affect your delivery reputation
# with email providers
def reactivate_and_retry(error)
Rails.logger.info("Error when sending #{message} to #{error.recipients.join(', ')}")
Rails.logger.info(error)

error.recipients.each do |recipient|
bounce = postmark_client.bounces(emailFilter: recipient).first
next unless bounce
postmark_client.activate_bounce(bounce[:id])
end

# Try again immediately
message.deliver
end
end
```

### ActionMailer 4 and below

Wrap any calls to `#deliver_now` in error handlers like the one described
in the [postmark](https://github.com/wildbit/postmark-gem#error-handling) gem
docs.

Rails 4.2 introduces `#deliver_later` but doesn’t support `rescue_from` for
mailer classes. Instead, use the following monkey patch for
`ActionMailer::DeliveryJob`.

``` ruby
# app/mailers/application_mailer.rb

class ApplicationMailer < ActionMailer::Base
default from: 'user@example.org'
end

class ActionMailer::DeliveryJob
rescue_from Postmark::InactiveRecipientError, with: :reactivate_and_retry

def postmark_client
::Postmark::ApiClient.new(ActionMailer::Base.postmark_settings[:api_token],
ActionMailer::Base.postmark_settings.except(:api_token))
end


# This is just an example. Sometimes you might not want to reactivate
# an address that hard bounced.
# Warning: Having too many bounces can affect your delivery reputation
# with email providers
def reactivate_and_retry(error)
Rails.logger.info("Error when sending a message to #{error.recipients.join(', ')}")
Rails.logger.info(error)

error.recipients.each do |recipient|
bounce = postmark_client.bounces(emailFilter: recipient).first
next unless bounce
postmark_client.activate_bounce(bounce[:id])
end

# Try again immediately
perform(*arguments)
end
end
```

## Additional information

Looking for the advanced usage examples? Check out [the documentation](https://github.com/wildbit/postmark-gem/blob/master/README.md) for the `postmark` gem. The `postmark-rails` gem is built on top of it, so you can benefit from all its features.

## Requirements

* `postmark` gem version 1.0 and higher is required.
* You will also need a Postmark account, a server and at least one sender signature set up to use it. To get an account, [sign up](https://postmarkapp.com/sign_up)!
### Additional information

Looking for the advanced usage examples? Check out [the documentation](https://github.com/wildbit/postmark-gem/blob/master/README.md) for the [postmark gem](https://github.com/wildbit/postmark-gem).
The `postmark-rails` gem is built on top of it, so you can benefit from all it's features.

## Note on Patches/Pull Requests

Expand All @@ -247,6 +83,16 @@ Looking for the advanced usage examples? Check out [the documentation](https://g
* Nicolás Sanguinetti
* Laust Rud Jacobsen (rud)

## Issues & Comments

Feel free to contact us if you encounter any issues with the library or Postmark API.
Please leave all comments, bugs, requests and issues on the Issues page.

## License

The Postmark Rails gem is licensed under the [MIT](http://www.opensource.org/licenses/mit-license.php) license.
Refer to the [LICENSE](https://github.com/wildbit/postmark-rails/blob/master/LICENSE) file for more information.

## Copyright

Copyright © 2010—2018 Wildbit LLC. See LICENSE for details.
Copyright © 2018 Wildbit LLC.
Binary file added postmark.png
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 02b5fe8

Please sign in to comment.