Iterable API Gem

Rubygem to interact with the Iterable API.

Source code on Gitlab.

Installation

gem install iterable-api-client

or with Bundler in your Gemfile

gem 'iterable-api-client'

Usage

Documentation

Documentation can be found on rubydoc or in this README

API Documentation

The Iterable API documentation can be a helpful reference for looking up all the possible endpoint data interactions. The docs outline all the possible parameters to each endpoints as well as custom data fields.

Configuration

Global Config

Configure the gem with a default global configuration to use.

Iterable.configure do |config|
  config.token = 'api-token'
end

Config Object

If you have multiple tokens to use you can create a Iterable::Config object with a different token from the global default and pass in on requests.

# Creating a new config with a different token
conf = Iterable::Config.new(token: 'new-token')

# Example of using it with the campaigns endpoints
# which will then make API requests using the passed in config
campaigns = Iterable::Campaigns.new(config)

Responses

Response objects will attempt to parse the API response as JSON using the multi_json gem so you can have your own JSON parser handle the loading of responses.

You can access some of the response data for example:

templates = Iterable::Templates.new
response = templates.all

# Check if the response code is a succesfull HTTP Code from 200-299
response.success?

# Get response code
response.code

# Body of response - will attempt to parse as JSON
response.body

# HTTP message
response.message

# Headers of response
response['Content-Type']
# => 'application/json; charset=utf-8'

# The URI used to make the request for the response
reponse.uri

API Endpoints

• Bulk Catalog Items
  • Create
  • Delete
• Campaigns
  • All
  • Create
  • Metrics
  • Child Campaigns
• Catalog Field Mappings
  • Get
  • Update
• Catalog Items
  • All
  • Create
  • Update
  • Get
  • Delete
• Catalogs
  • Create
  • Delete
  • Names
• Channels
  • All
• Commerce
  • Track Purchase
  • Update Cart
• Device
  • Register Device Token
• Email
  • View
  • Target
• Email Templates
  • Get
  • Update
  • Upsert
• Events
  • For Email
  • Bulk Track
  • Track
  • Track Push Open
• Experiments
  • Metrics
• Export
  • JSON
  • CSV
• In App
  • Messages
  • Target
  • Cancel
• Lists
  • All
  • Create
  • Delete
  • Get Users
  • Subscribe
  • Unsubscribe
• Message Types
  • All
• Metadata
  • Get
  • List Keys
  • Delete
  • Get Key
  • Remove Key
  • Add Key
• Push
  • Target
  • Cancel
• Push Templates
  • Get
  • Update
  • Upsert
• Templates
  • All
  • Get
• Users
  • Update
  • Bulk Update
  • Update Subscriptions
  • Bulk Update Subscriptions
  • For Email
  • By User ID
  • Get Fields
  • Update Email
  • Delete
  • Delete By ID
  • Register Browser Token
  • Disable Device
  • Get Sent Messages
  • Forget
• Workflows
  • Trigger

Bulk Catalog Items

Beta access only endpoint

Bulk Catalog Items Create

Endpoint: POST /catalogs/{catalogName}/items

catalog = 'my-catalog'
catalog_items = Iterable::BulkCatalogItems.new(catalog)
# Hash of item id to item values
create_items = {
  '122343453' => {
    name: 'item name',
    status: 'open'
  }
}
response = catalog_items.create(create_items, replace_uploaded_fields_only: true)
 # Use replace_uploaded_fields_only as true to update fields
 # of existing items. Otherwise the default is to replace
 # existing items

Bulk Catalog Items Delete

Endpoint: DELETE /catalogs/{catalogName}/items

catalog = 'my-catalog'
catalog_items = Iterable::BulkCatalogItems.new(catalog)
item_ids = ['12345', '12346', '12347']
response = catalog_items.delete(item_ids)

Campaigns

Campaigns All

Endpoint: GET /campaigns

campaigns = Iterable::Campaigns.new
response = campaigns.all

Campaigns Create

Endpoint: POST /campaigns/create

campaigns = Iterable::Campaigns.new
# List IDs to associate with the campaign
list_ids = [1234, 1235, 1236]
# Additional campaign attributes
attrs = { dataFields: { foo: 'bar' } }
response = campaigns.create 'name', 'template-id', list_ids, attrs

Campaigns Metrics

Endpoint: GET /campaigns/metrics

campaigns = Iterable::Campaigns.new
campaign_ids = [754321, 4321, 3456]
end_time = Time.now
start_time = end_time - (60 * 60* 24 * 7) # 7 days ago
response = campaigns.metrics campaign_ids, start_time, end_time

Campaigns Recurring

Endpoint: GET /campaigns/recurring/{id}/childCampaigns

campaigns = Iterable::Campaigns.new
response = campaigns.recurring 'campaign-id'

Catalogs

Beta access only endpoint

Catalogs Create

Endpoint: POST /catalogs/{catalogName}

catalog = 'my-catalog'
catalogs = Iterable::Catalogs.new(catalog)
response = catalogs.create

Catalogs Delete

Endpoint: DELETE /catalogs/{catalogName}

catalog = 'my-catalog'
catalogs = Iterable::Catalogs.new(catalog)
response = catalogs.delete

Catalogs Names

Endpoint: GET /catalogs/{catalogName}

catalog = 'my-catalog'
catalogs = Iterable::Catalogs.new(catalog)
params = { page: 1, pageSize: 20 }
response = catalogs.names(params)

Catalog Field Mappings

Beta access only endpoint

Catalog Field Mappings Get

Endpoint: GET /catalogs/{catalogName}/fieldMappings

catalog = 'my-catalog'
catalog_field_mappings = Iterable::CatalogFieldMappings.new(catalog)
response = catalog_field_mappings.get
response.body['params']['definedMappings']

Catalog Field Mappings Update

Endpoint: PUT /catalogs/{catalogName}/fieldMappings

catalog = 'my-catalog'
field_mappings = [{fieldName: 'test-field', fieldType: 'string'}]
catalog_field_mappings = Iterable::CatalogFieldMappings.new(catalog)
catalog_field_mappings.update(field_mappings)

Catalog Items

Beta access only endpoint

Catalog Items All

Endpoint: GET /catalogs/{catalogName}/items

catalog = 'my-catalog'
catalog_items = Iterable::CatalogItems.new(catalog)
response = catalog_items.all

Catalog Items Create

Endpoint: PUT /catalogs/{catalogName}/items/{itemId}

catalog = 'my-catalog'
item_id = '1234-abcd-1234-abcd'
catalog_items = Iterable::CatalogItems.new(catalog, item_id)
item_attrs = { name: 'item name', status: 'open' }
response = catalog_items.create(item_attrs)

Catalog Items Update

Endpoint: PATCH /catalogs/{catalogName}/items/{itemId}

catalog = 'my-catalog'
item_id = '1234-abcd-1234-abcd'
catalog_items = Iterable::CatalogItems.new(catalog, item_id)
item_attrs = { name: 'item name', status: 'open' }
response = catalog_items.update(item_attrs)

Catalog Items Get

Endpoint: GET /catalogs/{catalogName}/items/{itemId}

catalog = 'my-catalog'
item_id = '1234-abcd-1234-abcd'
catalog_items = Iterable::CatalogItems.new(catalog, item_id)
response = catalog_items.get

Catalog Items Delete

Endpoint: DELETE /catalogs/{catalogName}/items/{itemId}

catalog = 'my-catalog'
item_id = '1234-abcd-1234-abcd'
catalog_items = Iterable::CatalogItems.new(catalog, item_id)
response = catalog_items.delete

Catalogs

Beta access only endpoint

Catalogs Create

Endpoint: POST /catalogs/{catalogName}

catalog = 'my-catalog'
catalog_items = Iterable::Catalogs.new(catalog)
response = catalog_items.create

Catalogs Delete

Endpoint: DELETE /catalogs/{catalogName}

catalog = 'my-catalog'
catalog_items = Iterable::Catalogs.new(catalog)
response = catalog_items.delete

Catalogs Names

Endpoint: GET /catalogs/{catalogName}/names

catalog = 'my-catalog'
catalog_items = Iterable::Catalogs.new(catalog)
params = { page: 1, pageSize: 20 }
response = catalog_items.names(params)

Channels

Channels All

Endpoint: GET /channels

channels = Iterable::Channels.new
response = channels.all

Commerce

Commerce Track Purchase

Endpoint: POST /commerce/trackPurchase

# Set up items to track
items = [{
  id: 'abcd-1234-hjkl-4321',
  name: 'Mustard',
  price: 34.0,
  quantity: 13
}]
# Calculate total of items i.e. 34.0
total = items.reduce(0) { |total, item| total += item.fetch(:price, 0.0) }
# Gather user information for purchase
user = { userId: '42', email: '[email protected]' }

commerce = Iterable::Commerce.new
response = commerce.track_purchase total, items, user

Commerce Update Cart

Endpoint: POST /commerce/updateCart

# Items to update the user's cart with
items = [{
  id: 'abcd-1234-hjkl-4321',
  name: 'Mustard',
  price: 34.0,
  quantity: 13
}]
# User of the cart you want to update
user = { userId: '42', email: '[email protected]' }

commerce = Iterable::Commerce.new
response = commerce.update_cart items, user

Device

Device Register Token

Endpoint: POST /users/registerDeviceToken

data_fields = { some: 'data', fields: 'here' }
device = Device.new 'token', 'mobile-push-app', Iterable::Device::APNS, data_fields
device.register '[email protected]'

# Can pass in a user ID as well
device.register '[email protected]', '42'

Email

Email View

Endpoint: GET /email/viewInBrowser

email = Iterable::Email.new
response = email.view '[email protected]', 'message-id'

Email Target

Endpoint: GET /email/target

email = Iterable::Email.new
# User email and campaign to target
response = email.target '[email protected]', 42

# Can pass in more attributes like dataFields
response = email.target '[email protected]', 42, { dataFields: { first_name: 'Sally' } }

Email Templates

Email Templates Get

Endpoint: GET /templates/email/get

templates = Iterable::EmailTemplates.new
response = templates.get 'template-id'

Email Templates Update

Endpoint: POST /templates/email/update

templates = Iterable::EmailTemplates.new
# Additional template attributes
attrs = { metadata: {}, name: 'name', fromEmail: '[email protected]' }
response = templates.update 'template-id', attrs

Email Templates Upsert

Endpoint: POST /templates/email/update

templates = Iterable::EmailTemplates.new
# Additional template attributes
attrs = { metadata: {}, name: 'name', fromEmail: '[email protected]' }
response = templates.upsert 'client-template-id', attrs

Events

Events for Email

Endpoint: GET /events/{email}

events = Iterable::Events.new
# Default limit of 30
response = events.for_email '[email protected]'

Events Track

Endpoint: POST /events/track

events = Iterable::Events.new
# Any aditional attributes for the event
attrs = { campaignId: 42, dataFields: {} }
response = events.track 'event-name', '[email protected]', attrs

Events Track Bulk

Endpoint: POST /events/trackBulk

events = Iterable::Events.new
# Array of events to track
events_attrs = [
  { email: '[email protected]', eventName: 'event-name', campaignId: 42, dataFields: {} }
]
response = iterable_events.track_bulk events_attrs

Events Track Push Open

Endpoint: GET /events/{email}

events = Iterable::Events.new
response = events.for_email '[email protected]'
campaign_id = 42
message_id = 123
# Any aditional attributes for the event
attrs = { dataFields: {} }
response = events.track_push_open campaign_id, message_id, '[email protected]', attrs

Experiments

Experiments Metrics

Endpoint: GET /experiments/metrics

experiment_ids = [1, 2, 3, 4]
experiments = Iterable::Experiments.new experiment_ids
end_time = Time.now
start_time = end_time - (60 * 60* 24 * 7) # 7 days ago
response = experiments.metrics campaign_ids, start_time, end_time

Export

Export JSON

Endpoint: GET /export/data.json

exporter = Iterable::JsonExporter.new Iterable::Export::EMAIL_SEND_TYPE

# Export with an iterable range
response = exporter.export_range Iterable::Export::BEFORE_TODAY

# Export with a custom time range
end_time = Time.now
start_time = end_time - (60 * 60* 24 * 7) # 7 days ago
response = exporter.export start_time, end_time

Export CSV

Endpoint: GET /export/data.csv

exporter = Iterable::CsvExporter.new Iterable::Export::EMAIL_SEND_TYPE

# Export with an iterable range
response = exporter.export_range Iterable::Export::BEFORE_TODAY

# Export with a custom time range
end_time = Time.now
start_time = end_time - (60 * 60* 24 * 7) # 7 days ago
response = exporter.export start_time, end_time

In App

In App Messages

Endpoint: GET /inApp/getMessages

in_app = Iterable::InApp.new

# Get messages for a user by email
email = '[email protected]'
response = in_app.messages_for_email email, count: 10

# Get messages for a user by user_id
email = '[email protected]'
response = in_app.messages_for_user_id 42, count: 2

# Pass in query parameters
email = '[email protected]'
attrs = { 'platform' => 'iOS' }
response = in_app.messages_for_email email, attrs

In App Target

Endpoint: POST /inApp/target

in_app = Iterable::InApp.new

# Needs campaign ID and an optional email
email = '[email protected]'
attrs = { 'campaignId' => '123456asdf' }
response = in_app.target attrs: attrs, email: email

In App Cancel

Endpoint: POST /push/cancel

in_app = Iterable::InApp.new

# Needs campaign ID and an optional email and optional attrs for request
email = '[email protected]'
campaign_id = '12345asdf'
attrs = {}
response = in_app.target campaign_id: campaign_id, attrs: attrs, email: email

Lists

Lists All

Endpoint: GET /lists

lists = Iterable::Lists.new
response = lists.all

Lists Create

Endpoint: POST /lists

lists = Iterable::Lists.new
response = lists.create 'list-name'

Lists Delete

Endpoint: DELETE /lists/{listId}

lists = Iterable::Lists.new
response = lists.delete 'list-id'

Lists Get Users

Endpoint: GET /lists/getUsers

lists = Iterable::Lists.new
response = lists.users 'list-id'

Lists Subscribe

Endpoint: POST /lists/subscribe

lists = Iterable::Lists.new
subscribers = [
	{ email: '[email protected]', dataFields: {}, userId: '42' }
]
response = lists.subscribe 'list-id', subscribers

Lists Unsubscribe

Endpoint: POST /lists/unsubscribe

lists = Iterable::Lists.new
subscribers = [
	{ email: '[email protected]', dataFields: {}, userId: '42' }
]
response = lists.unsubscribe 'list-id', subscribers

Message Types

Message Types All

Endpoint: GET /messageTypes

metadata = Iterable::MessageTypes.new
response = metadata.all

Metadata

Metadata Get

Endpoint: GET /metadata

metadata = Iterable::Metadata.new
response = metadata.get

Metadata List Keys

Endpoint: GET /metadata/{table}

metadata_table = Iterable::MetadataTable.new 'table-name'
response = metadata_table.list_keys

# Next marker is thenext result set id which is returned by previous
# search if more hits exist
response = metadata_table.list_keys 'next-marker-id'

Metadata Delete Key

Endpoint: DELETE /metadata/{table}

metadata_table = Iterable::MetadataTable.new 'table-name'
response = metadata_table.delete

Metadata Get Key

Endpoint: GET /metadata/{table}/{key}

metadata_table = Iterable::MetadataTable.new 'table-name'
response = metadata_table.get 'metadata-key'

Metadata Remove Key

Endpoint: DELETE /metadata/{table}/{key}

metadata_table = Iterable::MetadataTable.new 'table-name'
response = metadata_table.remove 'metadata-key'

Metadata Add Key

Endpoint: PUT /metadata/{table}/{key}

metadata_table = Iterable::MetadataTable.new 'table-name'
value = { foo: 'bar', data: 'stuffs' }
response = metadata_table.add 'metadata-key', value

Push

Push Target

Endpoint: POST /push/target

push = Iterable::Push.new
campaign_id = '1234asdf'
email = '[email protected]' # optional
attrs = {} # optional extra params for the request
response = push.target campaign_id: campaign_id, email: email, attrs: attrs

Push Cancel

Endpoint: POST /push/cancel

push = Iterable::Push.new
campaign_id = '1234asdf'
email = '[email protected]' # optional
attrs = {} # optional extra params for the request
response = push.cancel email: email, campaign_id: campaign_id, attrs: attrs

Push Templates

Push Templates Get

Endpoint: GET /templates/push/get

templates = Iterable::PushTemplates.new
# Additional template params to query by
params = { locale: 'en-US' }
response = templates.get 'template-id', params

Push Templates Update

Endpoint: POST /templates/push/update

templates = Iterable::PushTemplates.new
# Additional template attrs to update
attrs = { name: 'Template', message: 'Template message'}
response = templates.update 'client-template-id', attrs

Push Templates Upsert

Endpoint: POST /templates/push/upsert

templates = Iterable::PushTemplates.new
# Additional template attrs to upsert
attrs = { name: 'Template', message: 'Template message'}
response = templates.upsert 'client-template-id', attrs

Templates

Templates All

Endpoint: GET /templates

templates = Iterable::Templates.new
# Additional params to filter and search by
params = { templateType: Iterable::Templates::BLAST_TYPE, messageMedium: Iterable::MessageTypes::EMAIL_MEDIUM }
response = templates.all params

Templates Get

Endpoint: GET /templates/getByClientTemplateId

templates = Iterable::Templates.new
response = templates.for_client_template_id 'client-template-id'

Users

Users Update

Endpoint: POST /users/update

users = Iterable::Users.new
# Additional attributes to send
attrs = { userID: 'custom-id' }
response = users.update '[email protected]', attrs

Users Bulk Update

Endpoint: POST /users/bulkUpdate

users = Iterable::Users.new
# Array of users to update by email with additional
# fields if needed
users_attrs = [
	{ email: '[email protected]', userID: 'custom-id' }
]
response = users.bulk_update users_attrs

Users Update Subscriptions

Endpoint: POST /users/updateSubscriptions

users = Iterable::Users.new
# Additional attributes to send
attrs = { userID: 'custom-id' }
response = users.update_subscriptions '[email protected]', attrs

Users Bulk Update Subscriptions

Endpoint: POST /users/bulkUpdateSubscriptions

users = Iterable::Users.new
# Array of users to update by email with additional
# fields if needed
users = [
	{ email: '[email protected]', userID: 'custom-id' }
]
response = users.bulk_update_subscriptions users

Users For Email

Endpoint: GET /users/{email}

users = Iterable::Users.new
response = users.for_email '[email protected]'

Users For ID

Endpoint: GET /users/byUserID/{userID}

users = Iterable::Users.new
response = users.for_id '42'

Users Get Fields

Endpoint: GET /users/getFields

users = Iterable::Users.new
response = users.fields

Users Update Email

Endpoint: POST /users/updateEmail

users = Iterable::Users.new
response = users.update_email '[email protected]', '[email protected]'

Users Delete

Endpoint: DELETE /users/{email}

users = Iterable::Users.new
response = users.delete '[email protected]'

Users Delete By ID

Endpoint: DELETE /users/byUserId/{userID}

users = Iterable::Users.new
response = users.delete_by_id '42'

Users Register Browser Token

Endpoint: POST /users/registerBrowserToken

users = Iterable::Users.new
# Additional attrs to associate with token
attrs = { userID: '42' }
response = users.register_browser_token '[email protected]', 'the-token', attrs

Users Disable Device

Endpoint: POST /users/registerBrowserToken

users = Iterable::Users.new
response = users.disable_device 'the-token', '[email protected]'

# Optionally can use a user ID over email
response = users.disable_device 'the-token', nil, '42'

Users Get Sent Messages

Endpoint: POST /users/update

users = Iterable::Users.new
# Additional params to filter and query by
params = { campaignId: 'custom-id', limit: 30 }
end_time = Time.now
start_time = end_time - (60 * 60* 24 * 7) # 7 days ago
response = users.sent_messages '[email protected]', start_time, end_time, params

Users Forget

Endpoint: POST /users/forget

users = Iterable::Users.new
# Additional params to filter and query by
email = '[email protected]'
response = users.forget email

Workflows

Workflows Trigger

Endpoint: POST /workflows/triggerWorkflow

workflows = Iterable::Workflows.new
# Additional attributes to send
attrs = { listId: 'listId' }
response = workflows.trigger 'workflow-id', attrs