sendwithus_ruby

Ruby bindings for sending email via the sendwithus API.

Installation

gem install send_with_us

or with Bundler:

gem 'send_with_us'
bundle install

Usage

Send

NOTE - If a customer does not exist by the specified email (recipient address), the send call will create a customer.

send_email arguments

template_id - string - Template ID being sent
to - hash - Recipients' email address
:data - hash - Email data
:from - hash - From name/address/reply_to
:cc - array - array of CC addresses
:bcc - array - array of BCC addresses
:files - array - array of files to attach, as strings or hashes (see below)
:esp_account - string - ESP account used to send email
:version_name - string - version of template to send
:headers - hash - custom email headers NOTE only supported by some ESPs
:tags - array - array of strings to attach as tags
:locale - string - Localization string

send_with arguments [DEPRECATED]

template_id - string - Template ID being sent
to - hash - Recipients' email address
data - hash - Email data
from - hash - From name/address/reply_to
cc - array - array of CC addresses
bcc - array - array of BCC addresses
files - array - array of files to attach, as strings or hashes (see below)
esp_account - string - ESP account used to send email
version_name - string - version of template to send
headers - hash - custom email headers NOTE only supported by some ESPs
tags - array - array of strings to attach as tags

For any Ruby project:

require 'rubygems'
require 'send_with_us'

begin
    obj = SendWithUs::Api.new( api_key: 'YOUR API KEY', debug: true )

    # required params
    result = obj.send_email(
        'template_id',
        { address: "user@example.com" })
    puts result

    # required params and locale
    result = obj.send_email(
        'template_id',
        { address: "user@example.com" }),
        locale: 'en-US'
    puts result

    # full cc/bcc support
    result = obj.send_email(
        'template_id',
        { name: 'Matt', address: 'recipient@example.com' },
        data: { company_name: 'TestCo' },
        from: { name: 'Company',
            address: 'company@example.com',
            reply_to: 'info@example.com' },
        cc: [
            { name: 'CC',
                address: 'cc@example.com' }
        ],
        bcc: [
            { name: 'BCC',
                address: 'bcc@example.com' },
            { name: 'BCC2',
                address: 'bcc2@example.com' }
        ])
    puts result

    # Attachment support
    result = obj.send_email(
        'template_id',
        { name: 'Matt', address: 'recipient@example.com' },
        data: { company_name: 'TestCo' },
        from: { name: 'Company',
            address: 'company@example.com',
            reply_to: 'info@example.com' },
        cc: [],
        bcc: [],
        files: [
          'path/to/file.txt',
          { filename: 'customfilename.txt', attachment: 'path/to/file.txt' },
          { filename: 'anotherfile.txt', attachment: File.open('path/to/file.txt') },
          { filename: 'unpersistedattachment.txt', attachment: StringIO.new("raw data") }
        ]
    )
    puts result

    # Set ESP account
    # See: https://help.sendwithus.com/support/solurtions/articles/1000088976-set-up-and-use-multiple
    result = obj.send_email(
        'template_id',
        { name: 'Matt', address: 'recipient@example.com' },
        data: { company_name: 'TestCo' },
        from: { name: 'Company',
            address: 'company@example.com',
            reply_to: 'info@example.com' },
        cc: [],
        bcc: [],
        files: [],
        esp_account: 'esp_MYESPACCOUNT')
    puts result

    # all possible arguments
    result = obj.send_email(
        'template_id',
        { name: 'Matt', address: 'recipient@example.com' },
        data: { company_name: 'TestCo' },
        from: {
          name: 'Company',
          address: 'company@example.com',
          reply_to: 'info@example.com'
        },
        cc: [
            { name: 'CC',
                address: 'cc@example.com' }
        ],
        bcc: [
            { name: 'BCC',
                address: 'bcc@example.com' },
            { name: 'BCC2',
                address: 'bcc2@example.com' }
        ],
        files: ['path/to/attachment.txt'],
        esp_account: 'esp_MYESPACCOUNT',
        version: 'v2',
        tags: ['tag1', 'tag2'],
        locale: 'en-US')
    puts result

    # send_with - DEPRECATED!
    result = obj.send_with(
        'template_id',
        { name: 'Matt', address: 'recipient@example.com' },
        { company_name: 'TestCo' },
        {
          name: 'Company',
          address: 'company@example.com',
          reply_to: 'info@example.com'
        },
        [
            { name: 'CC',
                address: 'cc@example.com' }
        ],
        [
            { name: 'BCC',
                address: 'bcc@example.com' },
            { name: 'BCC2',
                address: 'bcc2@example.com' }
        ],
        ['path/to/attachment.txt'],
		'esp_MYESPACCOUNT',
		'v2',
        ['tag1', 'tag2'],
        'en-US')
    puts result
rescue => e
    puts "Error - #{e.class.name}: #{e.message}"
end

Render a Template

email_id - string - Template ID being rendered
version_id - string - Version ID to render (optional)
data - hash - Email data to render the template with (optional)
data[:locale] - hash value - This option specifies the locale to render (optional)

require 'rubygems'
require 'send_with_us'

begin
    obj = SendWithUs::Api.new( api_key: 'YOUR API KEY', debug: true )

    result = obj.render(
        'template_id',
        'version_id',
        { company_name: 'TestCo' },

    puts result
rescue => e
    puts "Error - #{e.class.name}: #{e.message}"
end

Remove Customer from Drip Campaign

require 'rubygems'
require 'send_with_us'

begin
    obj = SendWithUs::Api.new( api_key: 'YOUR API KEY', debug: true )

    result = obj.drips_unsubscribe('customer@example.com')

    puts result
rescue => e
    puts "Error - #{e.class.name}: #{e.message}"
end

Using Drip Campaigns

require 'rubygems'
require 'send_with_us'

begin
    obj = SendWithUs::Api.new( api_key: 'YOUR API KEY', debug: true )

    # List campaigns
    result = obj.list_drip_campaigns()
    puts result

    # List steps of campaign dc_asdf1234
    result = obj.drip_campaign_details('dc_asdf1234')
    puts result

    # Add customer@example.com to campaign dc_asdf1234
    result = obj.start_on_drip_campaign('customer@example.com', 'dc_asdf1234')
    puts result

    OR

    # Add customer@example.com to campaign dc_asdf1234, with optional: email_data, locale, tags
    result = obj.start_on_drip_campaign('customer@example.com', 'dc_asdf1234', {total: '100.00'}, 'en-US', ['tag1', 'tag2'])
    puts result

    # Remove customer@example.com from campaign dc_asdf1234
    result = obj.remove_from_drip_campaign('cusomter@example.com', 'dc_asdf1234')
    puts result
    rescue => e
    puts "error - #{e.class.name}: #{e.message}"
end

Customers

Create/Update a Customer

customer_data = {:FirstName => "Visha"}
result = obj.customer_create("visha@example.com", customer_data)

Delete a Customer

result = obj.customer_delete("visha@example.com")

Add customer to group

obj.customer_add_to_group(email_address, group_id)

Remove customer from group

obj.customer_remove_from_group(email_address, group_id)

Customer Conversion Event

You can use the Conversion API to track conversion and revenue data events against your sent emails

NOTE: Revenue is in cents (eg. $100.50 = 10050)

# With Revenue
obj.customer_conversion('customer@example.com', 10050)

# Without Revenue
obj.customer_conversion('customer@example.com')

Templates

# List Templates
obj.list_templates() # Alternatively, obj.emails()

# Create Template
obj.create_template(name, subject, html, text)

# Delete Template
obj.delete_template(template_id)

# List Template Versions
obj.list_template_versions(template_id)

# Update Template Version
obj.update_template_version(template_id, version_id, name, subject, html, text)

# Create Template Version
obj.create_template_version(template_id, name, subject, html, text)

Groups

Groups are another way to "tag" customers in sendwithus. They can be thought of as lists.

# List groups
obj.get_groups()

# Create group
obj.create_customer_group(name, description)

# Update group
obj.update_customer_group(group_id, new_name, new_description)

# Delete group
obj.delete_customer_group(group_id)

Rails

For a Rails app, create send_with_us.rb in /config/initializers/ with the following:

SendWithUs::Api.configure do |config|
    config.api_key = 'YOUR API KEY'
    config.debug = true
end

In your application code where you want to send an email:

begin
    result = SendWithUs::Api.new.send_with('template_id', { address: 'recipient@example.com' }, { company_name: 'TestCo' })
    puts result
rescue => e
    puts "Error - #{e.class.name}: #{e.message}"
end

Take a look at our Mailer that you can use to replace ActionMailer

sendwithus_ruby_action_mailer

Logs

Optional Arguments:

count – The number of logs to return. Max: 100, Default: 100.
offset – Offset the number of logs to return. Default: 0
created_gt – Return logs created strictly after the given UTC timestamp.
created_gte – Return logs created on or after the given UTC timestamp.
created_lt – Return logs created strictly before the given UTC timestamp.
created_lte – Return logs created on or before the given UTC timestamp.

obj.logs(count: 1, offset: 1)

Errors

The following errors may be generated:

SendWithUs::ApiInvalidEndpoint - the target URI is probably incorrect or template_id is invalid
SendWithUs::ApiInvalidKey - the sendwithus API key is invalid
SendWithUs::ApiBadRequest - the API request is invalid
SendWithUs::ApiConnectionRefused - the target URI is probably incorrect
SendWithUs::ApiUnknownError - an unhandled HTTP error occurred

Internal

Build gem with

gem build send_with_us.gemspec

Publish gem with

gem push send_with_us-VERSION.gem

kiragrom / sendwithus_ruby