sendwithus_ruby

Ruby bindings for sending email via the sendwithus API.

sendwithus.com

Installation

gem install send_with_us

or with Bundler:

gem 'send_with_us'
bundle install

Usage

Send

send_email arguments

• email_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]

• email_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.drip_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', {location: 'Canada', total: '100.00'})
    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_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