Iterable API Gem
Rubygem to interact with the Iterable API.
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.
# The URI used to make the request for the response
reponse.uri
API Endpoints
- Campaigns
- Channels
- Commerce
- Device
- Email Templates
- Events
- Experiments
- Export
- Lists
- Message Types
- Metadata
- Push Templates
- Templates
- Users
- Workflows
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 Rrecurring
Endpoint: GET /campaigns/recurring/{id}/childCampaigns
campaigns = Iterable::Campaigns.new
response = campaigns.recurring 'campaign-id'
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 View
Endpoint: GET /email/viewInBrowser
email = Iterable::Email.new
response = email.view '[email protected]', 'message-id'
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 Push Open
Endpoint: GET /events/{email}
events = Iterable::Events.new
response = events.for_email '[email protected]'
campaign_id = 42
= 123
# Any aditional attributes for the event
attrs = { dataFields: {} }
response = events.track_push_open campaign_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
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
= Iterable::MessageTypes.new
response = .all
Metadata
Metadata Get
Endpoint: GET /metadata
= Iterable::Metadata.new
response = .get
Metadata List Keys
Endpoint: GET /metadata/{table}
= Iterable::MetadataTable.new 'table-name'
response = .list_keys
# Next marker is thenext result set id which is returned by previous
# search if more hits exist
response = .list_keys 'next-marker-id'
Metadata Delete Key
Endpoint: DELETE /metadata/{table}
= Iterable::MetadataTable.new 'table-name'
response = .delete
Metadata Get Key
Endpoint: GET /metadata/{table}/{key}
= Iterable::MetadataTable.new 'table-name'
response = .get 'metadata-key'
Metadata Remove Key
Endpoint: DELETE /metadata/{table}/{key}
= Iterable::MetadataTable.new 'table-name'
response = .remove 'metadata-key'
Metadata Add Key
Endpoint: PUT /metadata/{table}/{key}
= Iterable::MetadataTable.new 'table-name'
value = { foo: 'bar', data: 'stuffs' }
response = .add 'metadata-key', value
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 = [
{ email: '[email protected]', userID: 'custom-id' }
]
response = users.bulk_update users
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. '[email protected]', start_time, end_time, params
Workflows
Workflows Trigger
Endpoint: POST /workflows/triggerWorkflow
workflows = Iterable::Workflows.new
# Additional attributes to send
attrs = { listId: 'listId' }
response = workflows.trigger 'workflow-id', attrs