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

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'beginobj=SendWithUs::Api.new(api_key: 'YOUR API KEY',debug: true)# required paramsresult=obj.send_email('template_id',{address: "user@example.com"})putsresult# required params and localeresult=obj.send_email('template_id',{address: "user@example.com"}),locale: 'en-US'putsresult# full cc/bcc supportresult=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'}])putsresult# Attachment supportresult=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")}])putsresult# Set ESP account# See: https://help.sendwithus.com/support/solurtions/articles/1000088976-set-up-and-use-multipleresult=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')putsresult# all possible argumentsresult=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')putsresult# 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')putsresultrescue=>eputs"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'beginobj=SendWithUs::Api.new(api_key: 'YOUR API KEY',debug: true)result=obj.render('template_id','version_id',{company_name: 'TestCo'},putsresultrescue=>eputs"Error - #{e.class.name}: #{e.message}"end

Remove Customer from Drip Campaign

require'rubygems'require'send_with_us'beginobj=SendWithUs::Api.new(api_key: 'YOUR API KEY',debug: true)result=obj.drips_unsubscribe('customer@example.com')putsresultrescue=>eputs"Error - #{e.class.name}: #{e.message}"end

Using Drip Campaigns

require'rubygems'require'send_with_us'beginobj=SendWithUs::Api.new(api_key: 'YOUR API KEY',debug: true)# List campaignsresult=obj.list_drip_campaigns()putsresult# List steps of campaign dc_asdf1234result=obj.drip_campaign_details('dc_asdf1234')putsresult# Add customer@example.com to campaign dc_asdf1234result=obj.start_on_drip_campaign('customer@example.com','dc_asdf1234')putsresultOR# Add customer@example.com to campaign dc_asdf1234, with optional: email_data, locale, tagsresult=obj.start_on_drip_campaign('customer@example.com','dc_asdf1234',{total: '100.00'},'en-US',['tag1','tag2'])putsresult# Remove customer@example.com from campaign dc_asdf1234result=obj.remove_from_drip_campaign('cusomter@example.com','dc_asdf1234')putsresultrescue=>eputs"error - #{e.class.name}: #{e.message}"end

Customers

Get a Customer

customer=obj.customer_get("visha@example.com")

Create/Update a Customer

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

Delete a Customer

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

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)

Templates

# List Templatesobj.list_templates()# Alternatively, obj.emails()# Create Templateobj.create_template(name,subject,html,text)# Delete Templateobj.delete_template(template_id)# List Template Versionsobj.list_template_versions(template_id)# Update Template Versionobj.update_template_version(template_id,version_id,name,subject,html,text)# Create Template Versionobj.create_template_version(template_id,name,subject,html,text)

Rails

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

SendWithUs::Api.configuredo |config|
config.api_key='YOUR API KEY'config.debug=trueend

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

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

Take a look at our Mailer that you can use similarly to 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 - thetargetURIisprobablyincorrectortemplate_idisinvalidSendWithUs::ApiInvalidKey - thesendwithusAPIkeyisinvalidSendWithUs::ApiBadRequest - theAPIrequestisinvalidSendWithUs::ApiConnectionRefused - thetargetURIisprobablyincorrectSendWithUs::ApiUnknownError - anunhandledHTTPerroroccurred

Running tests

Use rake to run the tests:

$: rake

Troubleshooting

General Troubleshooting

• Enable debug mode
• Make sure you're using the latest Ruby client
• Capture the response data and check your logs — often this will have the exact error

Enable Debug Mode

Debug mode prints out the underlying request information as well as the data payload that gets sent to sendwithus. You will most likely find this information in your logs. To enable it, simply put debug: true as a parameter when instantiating the API object. Use the debug mode to compare the data payload getting sent to sendwithus' API docs.

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

Response Ranges

Sendwithus' API typically sends responses back in these ranges:

• 2xx – Successful Request
• 4xx – Failed Request (Client error)
• 5xx – Failed Request (Server error)

If you're receiving an error in the 400 response range follow these steps:

• Double check the data and ID's getting passed to Sendwithus
• Ensure your API key is correct
• Log and check the body of the response

Internal

Build gem with

gem build send_with_us.gemspec

Publish gem with

gem push send_with_us-VERSION.gem