Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
108 lines (73 sloc) 4.71 KB

SunDawg Responsys Client


This project is a Ruby gem to communicate with Responsys (, an enterprise email service provider. This code is neither officially supported nor endorsed by Responsys.

The purpose of this project is to provide a more friendly Ruby wrapper to their SOAP API. The initial ruby code was generated from their WSDL, as of April 2011, via the SOAP4R project ( Additional monkey fixes were needed to support SOAP headers that the Responsys API depends on.

What You Need

You will need a valid SOAP username and password to communicate with their API.


There are two key objects contained within the gem, the actual API Client, ResponsysClient, and the user object, Member.


The member object contains all of the user fields you want to replicate to Responsys in your email list.

It contains a class level list of attributes and system attributes that will be serialized into proper Responsys attributes for either a bulk export or API insert/update.

include SunDawg::Responsys

# Create fields we will syndicate to Responsys

# Clear anything previously set (just in case)

# Set our fields

# Set system level Responsys fields
Member.add_field :customer_id, true
Member.add_field :email_permission_status, true
Member.add_field :email_address, true

# Set application level Responsys fields 
Member.add_field :user_type
Member.add_field :first_name
Member.add_field :last_name
Member.add_field :gender

This will declare the attributes for Responsys and define setters/getters for the member object. This means you can do:

member =
member.customer_id = 123
member.email_address = ""
member.first_name = "chris"
=> "chris"

You can also set an attributes hash in the method constructor or attributes accessor.

member = => 123, :email_address => "")
member.attributes.merge({:first_name => "Chris", :user_type => "basic"})

What are the difference between “system” and “application” fields? Responsys indicates that system fields are those fields that are part of every basic customer list. When communicating with them, they are denoted with a trailing a “_”, such as CUSTOMER_ID_ and EMAIL_ADDRESS_. Application fields are specific to your relationship with Responsys and are just FOO and BAR, without the trailing underscore. The member object tries to abstract this convention away.

CSV Handling

Responsys supports multiple methods of bulk importing user data through CSV via their dashboard and SFTP. When you have your member object declared, you can quickly serialize your user object into a Responsys member.

members = []
your_user_models.each do |user|
  members << convert_to_responsys(user)
Member.to_csv_file(members, "/tmp/responsys.csv", true)

This will create a csv file of members with a header row on top. Please note that the to_csv_file method will append to any existing CSV. This is done to allow you to append to a file if you decide to query your user database in batches, like so via ActiveRecord.

Member.to_csv_file([], "/tmp/responsys.csv", true)
User.find_in_batches do |group|
  members = []
  group.each do |user|
    members << convert_to_responsys(user)
  Member.to_csv_file(members, "/tmp/responsys.csv", false)

This will first create a header row, then create batches of members without the header row in the same file.

Responsys also encourages the use of “splitted” CSV files where you send two CSV files linked by customer_id. This allows it to handle large uploads easier by separating data intrinsic to the user.

This can be achieved be doing:

# Declare the fields that belong on the basic user profile. Everything else is "data" that is not really intrinsic to the user. Other fields, like foo and bar will be placed in "data".
Member.profile_fields = [:customer_id, :email_permission_status, :email_address, :user_type]
Member.to_csv_file(members, "/tmp/user.csv", "/tmp/data.csv", false)

You can also parse the response CSV file from Responsys. This is useful to find out which records were not accepted by Responsys and perhaps indicate in your database that the user is invalid for some reason. It is assumed that you have declared the attributes of your Member beforehand.

Member.add_field :customer_id, true
results = Member.parse_feedback_csv("/tmp/feedback.csv")
results.each_pair do |member, reason|
  user = User.find(member.customer_id)
  user.reason_for_failed_replicate = reason


This gem is still in development mode. It is not hosted on yet.