Ruby Bindings for Apostle.io
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
spec
.gitignore
.travis.yml
Gemfile
LICENSE
README.md
Rakefile
apostle.gemspec

README.md

Apostle Ruby

Build Status Gem Version

Ruby bindings for Apostle.io

Rails

If you're using Rails, you should know that apostle-rails exists. Knowledge of this Gem is still important however, as apostle-rails will bring this gem along for the ride.

Installation

Add this line to your application's Gemfile:

gem 'apostle'

And then execute:

$ bundle

Or install it yourself as:

$ gem install apostle

Domain Key

You will need to provide your apostle domain key to send emails. Apostle looks in ENV['APOSTLE_DOMAIN_KEY'], or you can set it manually.

Apostle.configure do |config|
	config.domain_key = 'Your domain key'
end

Sending Email

Sending an email is easy. A minimal email might look like this.

Apostle::Mail.new('welcome_email', email: "mal@mal.co.nz").deliver!

The first param Apostle::Mail expects is the template slug, and the second is a hash of mail information.

Adding data

You can assign any data you want, and it will be passed to the API for hydrating your template. If you had a template that required {{username}}, you could send them like this:

mail = Apostle::Mail.new('welcome_email', email: 'mal@mal.co.nz', username: 'Snikch').deliver!

You can also set any data directly on the mail object.

mail = Apostle::Mail.new('welcome_email')
mail.email = 'mal@mal.co.nz'
mail.username = 'Snikch'
mail.deliver!

Setting name

In addition to the email, you can provide the name to be used in the to field of the email.

Apostle::Mail.new('welcome_email', email: "mal@mal.co.nz", name: "Mal Curtis").deliver!
# Sends email with "to: Mal Curtis <mal@mal.co.nz>"

Setting from address

Although the from address is set up in your template, you can override that for any individual email, or provide a reply to address.

mail.from = 'support@example.com'
mail.reply_to = 'noreply@example.com'

Adding Cc and Bcc

You can add Cc and Bcc with the Apostle mail object.

mail.cc = 'samplecc@example.com'
mail.bcc = 'samplebcc@example.com'

It also supports adding multiple emails to Cc and Bcc as an array,

mail.cc = ['email1@example.com', 'email2@example.com']
mail.bcc = ['sample1@example.com', 'sample2@example.com']

Additional Headers

You can provide custom headers to be sent with your email via #header.

# Set
mail.header 'X-Some-Header', 'my custom header'

# Get
mail.header 'X-Some-Header'
=> "my custom header"

Attachments

You can send attachments by adding to attachments hash on the mail object.

mail.attachments["invoice.pdf"] = File.read("invoices/12345.pdf")

Sending Multiple Emails

To speed up processing, you can send more than one email at a time.

queue = Apostle::Queue.new

3.times do |count|
	queue << Apostle::Mail.new("welcome_email", email: "user#{count}@example.com")
end

queue.deliver!

If any of the emails are invalid this will raise an exception and no emails will be sent; i.e. missing a template slug, or delivery address.

You can either catch Apostle::DeliveryError, or call the safer #deliver, then access a hash of results on the queue via #results.

queue = Apostle::Queue.new

queue << Apostle::Mail.new("welcome_email", email: "mal@mal.co.nz")
queue << Apostle::Mail.new("welcome_email")

queue.deliver
=> false

queue.results
=> {
	:valid=>[#<Apostle::Mail:0x007fcee5ab2550>],
	:invalid=>[#<Apostle::Mail:0x007fcee5ab23c0>]
}
queue.results[:invalid].first._exception
=> #<Apostle::DeliveryError @message="No recipient provided">

Helpers

You have access to #size and #clear on the queue. You can use this to group requests.

users.each do |user|
	queue << Penpan::Mail.new('welcome', email: user.email)
	if queue.size == 1000
		queue.deliver
		queue.clear
	end
end

Or use the helper method #flush, which does exactly this, calls #deliver then #clear if delivery succeeds.

users.each do |user|
	queue << Penpan::Mail.new('welcome', email: user.email)
	if queue.size == 1000
		queue.flush
	end
end

Delivery Failure

If delivery to Apostle fails, an exception will be raised. There are various events that could cause a failure:

  • Apostle::Unauthorized: The domain key was not provided, or valid
  • Apostle::UnprocessableEntity: The server returned a 422 response. Check the content of the message for more details, but this will likely be a validation / content error
  • Apostle::ServerError: Something went wrong at the Apostle API, you should try again with exponential backoff
  • Apostle::Forbidden: The server returned a 403 response. This should not occur on the delivery API
  • Apostle::DeliveryError: Anything which isn't covered by the above exceptions

Who

Created with ♥ by Mal Curtis (@snikchnz)

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request