Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
The ecircle gem: Eases the pain when dealing with the most horrible API on this planet
Ruby

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
spec
.gitignore
.rvmrc
.travis.yml
Gemfile
Gemfile.lock
README.md
Rakefile
ecircle.gemspec

README.md

Travis Build Status

Build Status

Synopsis

This gem aims to be a full-fledged solution for the ecircle API, the synchronous one and the asynchronous one.

The API coverage is far from complete, however as far as I can see the most useful / frequent methods are covered.

The existing API methods can be considered stable and are used in production.

Features

Synchronous API

The following methods are implemented:

  • createMember
  • createOrUpdateUserByEmail
  • deleteGroup
  • deleteMember
  • logon (only for debugging purposes)
  • logout
  • sendParametrizedSingleMessageToUser

See the online API documentation for details on arguments and return values

Asnchronous API

Since the asynchronous API is neither documented by ecircle nor intuitive at all, you're on your own. Jump to the examples section and good luck.

To do

  • Implement missing API methods:
    • createOrUpdateGroup
    • deleteUser
    • deleteUserByEmail
    • lookupGroups
  • Write specs

Configuration

Ecircle.configure do |config|
  config.user       = 'your@user.com'
  config.sync_realm = 'http://your.realm.com'
  config.password   = 'your_password'
end

The reason for the unusual configuration setting "sync_realm" is that there is also an asynchronous ecircle API with a different realm.

Logon

The ecircle gem does the session handling for you, there is no need to logon explicitly. Session tokens will be re-used to keep the number of session related traffic to a minimum.

Examples

Synchronous API

# Given you have called Ecircle.configure appropriatly...

# 1.) Create a user
uid = Ecircle.create_or_update_user_by_email 'your@email.com'
puts "Ecircle user ID: #{uid}"

# 2.) Add this user as a member to a group - e.g. for newsletters
mid = Ecircle.create_member uid, 'your_group_id'
puts "Ecircle member Id: #{mid}"

# 3.) Delete member from group - e.g. when he unsubscribes
Ecircle.delete_member mid

# 4.) Send the user a transactional email:
Ecircle.send_parametrized_single_message_to_user uid,
                                                your_template_id_at_ecircle,
                                                [ :name, :message ],
                                                [ 'Tom', 'welcome!' ]

# 5.) Delete the group
Ecircle.delete_group your_group_id

# 6.) Log out
Ecircle.logout

Asynchronous API

Ecircle.configure do |config|
  config.user        = 'your@user.com'
  config.async_realm = 'http://your.async.realm.com' # IMPORTANT - different realm.
  config.password    = 'your_password'
end

@options = {
  :endpoint                     => 'http://your.domain/eC-MessageService',
  :request_id                   => '1234',
  :group_id                     => '5678',
  :send_out_date                => 70.minutes.from_now, # Must be at least one hour in the future!
  :send_date_for_report         => 140.minutes.from_now,  # Must be at least one hour in the future *after* dispatching!
  :report_email                 => 'your@report.de',
  :report_email_name            => 'Your name',
  :subject                      => 'Newsletter',
  :text                         => 'Newsletter text content',
  :html                         => 'Newsletter html content'
}

Ecircle::JobPackage.send_async_message_to_group @options

Documentation

Something went wrong with that request. Please try again.