LeToteTeam / unresponsys

Ruby gem for Responsys email marketing software

Note: This gem is no longer maintained.

---

What is the purpose of this gem? It is an opinionated wrapper for Responsys email marketing software. It uses the new REST API, while existing gems are wrapping the old SOAP API.

Contents

1. Setup
2. Lists
3. Members
4. Messages
5. Events
6. Extension Tables
7. Supplemental Tables

Setup

Initialize your client:

client = Unresponsys::Client.new(
  username: 'YOUR_USERNAME',
  password: 'YOUR_PASSWORD',
  interact: 2||5
)

The interact option is optional, and can be either 2 or 5. If omitted, it will default to 2.

Lists

From the documentation:

Lists are used to store audience database records—members of your audience might be leads, prospects, customers, contacts, consumers, or visitors, depending on your terminology. The standard set of fields in a list includes:

• Recipient ID (RIID), an internalOracle Responsys-assigned identifier that allows the behavior of individual recipients to be tracked over time.
• Email address, mobile number, postal address, which are standard contact channel fields
• Permission/Opt-in status fields for the various marketing channels (email, mobile, postal)
• Email format preference (HTML or text)
• Derived fields for ISP and domain
• Last modified and created timestamps In addition, lists can have a number of custom, user-defined fields that you use to maintain a rich audience profile for targeting and personalization purposes.

Find a list

client.lists.find('mylist')

Accepts a list name (string). Returns an Unresponsys::List instance

Find list member

list = client.lists.find('mylist')
list.members.find('[e-mail]')

Accepts an email address. Returns an Unresponsys::Member instance

Throws an Unresponsys::NotFound if no member exists

New list member

list = client.lists.find('mylist')
list.members.new('[e-mail]')

Accepts an email address (string). Returns an Unresponsys::Member instance

Members

Members belong to a particular list and can be instantiated through that list

There are several reserved, immutable fields which become attr_reader

• riid - the responsys id
• email_address - email address
• mobile_number - mobile number

You can also create up to 80 custom fields (in the Responsys dashboard) which become attr_accessor

Save a member

member = list.members.find('[e-mail]')
member.some_field = 'blablabla'
member.save

Create or update a list member. Returns true or false

Messages

New Message

member = list.members.find('[e-mail]')
message = member.messages.new('ReferredFriend', referral_code: '123456')

Accepts an campaign name (string) and a hash of key-value properties (optional) which can be used to personalize the email

Save Message

message = member.messages.new('ReferredFriend', referral_code: '123456')
message.save

Returns true on success or throws an error

Sends the message

Events

New event

member = list.members.find('[e-mail]')
event = member.events.new('ReferredFriend')

Accepts an event name (string)

Custom events must be defined on the account page of the Responsys dashboard before you can start sending them

Save event

event = member.events.new('ReferredFriend')
event.save

Returns true on success or throws an error

Throws a Unresponsys::NotFound if you have not defined the event on the account page of the Responsys dashboard

Extension Tables

From the documentation:

One or more Profile Extension Tables can be associated with a Profile List. There must be a one-to-one relationship between a record in a Profile Extension Table and its parent Profile List. Profile Extension Tables provide an attractive and efficient way to organize and process audience data. Similar to data in Profile Lists, audience data in Profile Extension Tables can be used for segmentation and targeting in Filters as well as Programs

Find extension table

member = list.members.find('[e-mail]')
table = member.extension_tables.find('MyExtensionTable')

Extension tables belong to a particular list and are accessed through a list member. Each list member has one corresponding entry in the extension table. Tables need to be created and edited through the dashboard.

Takes a table name (string). Returns an instance of Unresponsys::ExtensionTable

Update extension table

member = list.members.find('[e-mail]')
table = member.extension_tables.find('MyExtensionTable')
table.update(favorite_color: 'blue')

Returns true or false

Supplemental Tables

From the documentation:

As its name indicates, a supplemental table is a collection of database records that supplements a list with additional related information. The connections between a table and a list is made via a data extraction key, or key field, that is present in both the table and the list. Because you define the schema for any tables you create, you can use them for a wide variety of purposes, ranging from message personalization and dynamic content to storing form responses and campaign events.

Find supplemental table

folder  = client.folders.find('MyFolder')
table   = folder.supplemental_tables.find('MyTable')

Tables belong to a folder and need to be accessed through it. Tables need to be created and edited through the dashboard. This gem assumes that your table has one primary key, called ID_, which is an integer. This can be setup through the dashboard.

Takes a table name (string). Returns an instance of Unresponsys::SupplementalTable

Find row

table = folder.supplemental_tables.find('MyTable')
table.rows.find(123)

Takes an id (integer). Returns an instance of Unresponsys::Row or throws an Unresponsys::NotFound

New row

table = folder.supplemental_tables.find('MyTable')
table.rows.new(124)

Takes an id (integer). Returns an instance of Unresponsys::Row

Save row

row = table.rows.find(123)
row.title = 'My Title'
row.save

Returns true or false

Destroy row

row = table.rows.find(123)
row.destroy

Returns true or false