# Note

EmailDirect is now [Campaigner](http://campaigner.com/).
The API endpoint, https://edapi.campaigner.com/v1/, was created by Campaigner to handle old EmailDirect API.
Use `v1.3.4` if you use `Hashie >= 3.0.0`.

# emaildirect

A ruby library which implements the complete functionality of the REST [Campaigner EmailDirect API](https://media.campaigner.com/apidocs/edapi/#overview).

## 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](http://fakeweb.rubyforge.org/))

    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](https://media.campaigner.com/apidocs/edapi/#overview) and take a look at the code for that function.

## Credits
- Jason Rust
- [createsend-ruby](https://github.com/campaignmonitor/createsend-ruby) library for inspiration on how to write a decent REST API wrapper.