Skip to content

Latest commit

 

History

History
336 lines (273 loc) · 8.67 KB

README.md

File metadata and controls

336 lines (273 loc) · 8.67 KB
Raw

sendwithus_ruby

Ruby bindings for sending email via the sendwithus API.

sendwithus.com

Build Status

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: "[email protected]" })
    puts result

    # required params and locale
    result = obj.send_email(
        'template_id',
        { address: "[email protected]" }),
        locale: 'en-US'
    puts result

    # full cc/bcc support
    result = obj.send_email(
        'template_id',
        { name: 'Matt', address: '[email protected]' },
        data: { company_name: 'TestCo' },
        from: { name: 'Company',
            address: '[email protected]',
            reply_to: '[email protected]' },
        cc: [
            { name: 'CC',
                address: '[email protected]' }
        ],
        bcc: [
            { name: 'BCC',
                address: '[email protected]' },
            { name: 'BCC2',
                address: '[email protected]' }
        ])
    puts result

    # Attachment support
    result = obj.send_email(
        'template_id',
        { name: 'Matt', address: '[email protected]' },
        data: { company_name: 'TestCo' },
        from: { name: 'Company',
            address: '[email protected]',
            reply_to: '[email protected]' },
        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: '[email protected]' },
        data: { company_name: 'TestCo' },
        from: { name: 'Company',
            address: '[email protected]',
            reply_to: '[email protected]' },
        cc: [],
        bcc: [],
        files: [],
        esp_account: 'esp_MYESPACCOUNT')
    puts result

    # all possible arguments
    result = obj.send_email(
        'template_id',
        { name: 'Matt', address: '[email protected]' },
        data: { company_name: 'TestCo' },
        from: {
          name: 'Company',
          address: '[email protected]',
          reply_to: '[email protected]'
        },
        cc: [
            { name: 'CC',
                address: '[email protected]' }
        ],
        bcc: [
            { name: 'BCC',
                address: '[email protected]' },
            { name: 'BCC2',
                address: '[email protected]' }
        ])
        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: '[email protected]' },
        { company_name: 'TestCo' },
        {
          name: 'Company',
          address: '[email protected]',
          reply_to: '[email protected]'
        },
        [
            { name: 'CC',
                address: '[email protected]' }
        ],
        [
            { name: 'BCC',
                address: '[email protected]' },
            { name: 'BCC2',
                address: '[email protected]' }
        ])
        ['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)
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('[email protected]')

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

Using Drips 2.0

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 [email protected] to campaign dc_asdf1234
    result = obj.start_on_drip_campaign('[email protected]', 'dc_asdf1234', {location: 'Canada', total: '100.00'})
    puts result

    # Remove [email protected] from campaign dc_asdf1234
    result = obj.remove_from_drip_campaign('[email protected]', '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("[email protected]", customer_data)

Delete a Customer

result = obj.customer_delete("[email protected]")

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('[email protected]', 10050)

# Without Revenue
obj.customer_conversion('[email protected]')

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: '[email protected]' }, { 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

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