Giters

jimneath / sendwithus_ruby

Sendwithus Ruby Client

Home Page:https://www.sendwithus.com

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

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

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)

Get logs for customer

This will retrieve email logs for a customer.

Optional Arguments:

  • count – The number of logs to return. Max: 100, Default: 100.
  • created_gt – Return logs created strictly after the given UTC timestamp.
  • created_lt – Return logs created strictly before the given UTC timestamp.
obj.customer_email_log('customer@example.com', count: 1)

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

About

Sendwithus Ruby Client

https://www.sendwithus.com

License:Apache License 2.0

Languages

Language:Ruby 100.0%