Note
EmailDirect is now Campaigner.
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.
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.