kfarst/emaildirect-ruby

Ruby Wrapper for the Email Direct REST (v5) API

emaildirect

A ruby library which implements the complete functionality of the REST (v5) Email Direct API.

Installation

Plain ruby

gem install emaildirect
require 'emaildirect'
EmailDirect.api_key = 'your_api_key'

Rails integration

In your gemfile:

gem 'emaildirect'

In an initializer:

EmailDirect.api_key = 'your_api_key'

Examples

Retrieve a list of all your publications.

EmailDirect::Publication.all.Publications.each do |pub|
  puts "#{pub.PublicationID}: #{pub.Name}"
end

Results in:

1: Publication One
2: Publication Two

Create, then remove a Publication

response = EmailDirect::Publication.create('Test', :Description => 'Test Publication')
sub = EmailDirect::Publication.new(response.publicationID)
sub.delete

Updating a subscriber's custom fields

A single attribute:

EmailDirect::Subscriber.new(email).update_custom_field :FirstName, 'Pat'

Multiple attributes:

EmailDirect::Subscriber.new(email).update_custom_fields :FirstName => 'Pam', :LastName => 'Sinivas'

When creating a subscriber

EmailDirect::Subscriber.create(email, :Publications => [1], :CustomFields => { :FirstName => 'Pam', :LastName => 'Sinivas' }

ActionMailer integration

You can use send your ActionMailer email through Email Direct using their Relay Send functionality by setting up a new delivery method in an initalizer:

 ActionMailer::Base.add_delivery_method :emaildirect, EmailDirect::Mailer,
                                        :category_id => 1,
                                        :options   => { :Force => true }

And in your ActionMailer class:

defaults :delivery_method => :emaildirect

or for just a particular message:

def welcome(user) do
  mail :to => user.email,
       :delivery_method => :emaildirect
end

Handling errors

If the emaildirect API returns an error, an exception will be thrown. For example, if you attempt to create a subscriber with an invalid email address:

begin
  response = EmailDirect::Subscriber.create('bademail')
  rescue EmailDirect::BadRequest => br
    puts "Bad request error: #{br}"
    puts "Error Code:    #{br.data.ErrorCode}"
    puts "Error Message: #{br.data.Message}"
  rescue Exception => e
    puts "Error: #{e}"
end

Results in:

Bad request error: The EmailDirect API responded with the following error - 101: Invalid Email Address
Error Code:    101
Error Message: Invalid Email Address

Disabling for development/testing

A helper method is provided to disable talking to the EmailDirect REST server (requires the Fakeweb gem)

EmailDirect.disable

Expected input and output

The best way of finding out the expected input and output of a particular method in a particular class is to read the API docs and take a look at the code for that function.

Credits

• Jason Rust
• createsend-ruby library for inspiration on how to write a decent REST API wrapper.