Letter::Mx

The Letter-MX-GEM is a lightweight GEM for accessing the Letter.MX subscriber REST web services.

Installation

Add this line to your application's Gemfile:

gem 'letter-mx'

And then execute:

$ bundle

Or install it yourself as:

$ gem install letter-mx

Usage

Basics

# Instantiate the API that is ready to make calls to Letter.mx
lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])

# Call one of the provided methods (e.g. list_subscribers)
response = lettermx.list_subscribers(query: {offset: 0, limit: 3})

# Get data from the response
subscribers = response.data

# Print useful http informations
puts "--- HTTP -----------------------------------------------------------------------"
puts "Status: #{response.http_status}"
puts "Body:"
puts response.http_body
puts

# Iterate over the result and print details of each subscriber
subscribers.each do |subscriber|
  puts "--- Subscriber -----------------------------------------------------------------"
  puts "ID.................: #{subscriber["id"]}"
  puts "User ID............: #{subscriber["user_id"]}"
  puts "Key................: #{subscriber["key"]}"
  puts "Email..............: #{subscriber["email"]}"
  puts "Firstname..........: #{subscriber["first_name"]}"
  puts "Lastname...........: #{subscriber["last_name"]}"
  puts "Optional 1.........: #{subscriber["optional_1"]}"
  puts "Optional 2.........: #{subscriber["optional_2"]}"
  puts "Optional 3.........: #{subscriber["optional_3"]}"
  puts "Status.............: #{subscriber["status"]}"
  puts "Created At.........: #{subscriber["created_at"]}"
  puts "Updated At.........: #{subscriber["updated_at"]}"
  puts "Soft Bounce Count..: #{subscriber["soft_bounce_count"]}"
  puts
end

Get Subscribers (GET /api/contacts)

lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])
response = lettermx.list_subscribers
puts response.data

[
  {
    "id"=>100, 
    "user_id"=>1, 
    "key"=>"ojgcrmjs", 
    "email"=>"[email protected]", 
    "first_name"=>nil, 
    "last_name"=>nil, 
    "optional_1"=>nil, 
    "optional_2"=>nil, 
    "optional_3"=>nil, 
    "status"=>"active", 
    "created_at"=>"2013-11-09T07:43:48.000+01:00", 
    "updated_at"=>"2013-11-09T07:43:48.000+01:00", 
    "soft_bounce_count"=>0
  }, 
  {
    "id"=>101, 
    "user_id"=>1, 
    "key"=>"jyyazhbl", 
    "email"=>"[email protected]", 
    "first_name"=>nil, 
    "last_name"=>nil, 
    "optional_1"=>nil, 
    "optional_2"=>nil, 
    "optional_3"=>nil, 
    "status"=>"active", 
    "created_at"=>"2013-11-11T12:41:48.000+01:00", 
    "updated_at"=>"2013-11-11T12:41:48.000+01:00", 
    "soft_bounce_count"=>0
  },
  ...
]

Count Subscribers (GET /api/contacts/count)

lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])
response = lettermx.count_subscribers
puts response.data

{
  "count"=>5
}

Get Subscriber (GET /api/contacts/100)

lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])
response = lettermx.get_subscribers(100)
puts response.data

{
  "id"=>100, 
  "user_id"=>1, 
  "key"=>"ojgcrmjs", 
  "email"=>"[email protected]", 
  "first_name"=>nil, 
  "last_name"=>nil, 
  "optional_1"=>nil, 
  "optional_2"=>nil, 
  "optional_3"=>nil, 
  "status"=>"active", 
  "created_at"=>"2013-11-09T07:43:48.000+01:00", 
  "updated_at"=>"2013-11-09T07:43:48.000+01:00", 
  "soft_bounce_count"=>0
}

Add Subscriber (POST /api/contacts)

lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])

new_subscriber = {
  email: "[email protected]",
  first_name: "John",
  last_name: "Doe"
}

response = lettermx.add_subscriber(new_subscriber)
puts response.data

{
  "id": 110,
  "user_id": 1,
  "key": "tbythqbn",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "optional_1": null,
  "optional_2": null,
  "optional_3": null,
  "status": "unconfirmed",
  "created_at": "2013-11-14T15:01:48.000+01:00",
  "updated_at": "2013-11-14T15:01:48.000+01:00",
  "soft_bounce_count": 0
}

Update Subscriber (PUT /api/contacts/100)

lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])

existing_subscriber = {
  first_name: "John",
  last_name: "Doe"
}

response = lettermx.update_subscriber(100, existing_subscriber)
puts response.data

{
  "id"=>100, 
  "user_id"=>1, 
  "key"=>"ojgcrmjs", 
  "email"=>"[email protected]", 
  "first_name"=>"John", 
  "last_name"=>"Doe", 
  "optional_1"=>nil, 
  "optional_2"=>nil, 
  "optional_3"=>nil, 
  "status"=>"active", 
  "created_at"=>"2013-11-09T07:43:48.000+01:00", 
  "updated_at"=>"2013-11-09T07:43:48.000+01:00", 
  "soft_bounce_count"=>0
}

Remove Subscriber (DELETE /api/contacts/100)

lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])
response = lettermx.remove_subscriber(100)
puts response.data

{
  "id"=>100, 
  "user_id"=>1, 
  "key"=>"ojgcrmjs", 
  "email"=>"[email protected]", 
  "first_name"=>"John", 
  "last_name"=>"Doe", 
  "optional_1"=>nil, 
  "optional_2"=>nil, 
  "optional_3"=>nil, 
  "status"=>"deleted", 
  "created_at"=>"2013-11-09T07:43:48.000+01:00", 
  "updated_at"=>"2013-11-09T07:43:48.000+01:00", 
  "soft_bounce_count"=>0
}

Get API limit (default) (GET /api/contacts/limit-default)

lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])
response = lettermx.subscribers_api_limit_default
puts response.data

{
  "limit_default"=>250
}

Get API limit (max) (GET /api/contacts/limit-max)

lettermx = LetterMX::Api.new(ENV["app_key"], ENV["api_key"])
response = lettermx.subscribers_api_limit_max
puts response.data

{
  "limit_max"=>3000
}

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