send_with_us 1.8.0 → 1.9.0

data/CHANGELOG.md

@@ -1,3 +1,4 @@
+1.9.0 - Locale support.  Introduce send_email().  Deprecate send_with().
 1.8.0 - Tags support for send_with
 1.7.0 - 
 1.6.0 - 

data/README.md

@@ -23,7 +23,21 @@ bundle install
 
 ### Send
 
-#### send_with parameters
+#### 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
@@ -45,40 +59,32 @@ require 'send_with_us'
 begin
     obj = SendWithUs::Api.new( api_key: 'YOUR API KEY', debug: true )
 
-    # only required params
-    result = obj.send_with(
+    # required params
+    result = obj.send_email(
         'template_id',
         { address: "user@example.com" })
     puts result
 
-    # with all optional params
-    result = obj.send_with(
+    # required params and locale
+    result = obj.send_email(
         'template_id',
-        { name: 'Matt', address: 'recipient@example.com' },
-        { company_name: 'TestCo' },
-        {
-          name: 'Company',
-          address: 'company@example.com',
-          reply_to: 'info@example.com'
-        },
-        ['path/to/attachment.txt'],
-		'esp_MYESPACCOUNT',
-		'v2') # version name
+        { address: "user@example.com" }),
+        locale: 'en-US'
     puts result
 
     # full cc/bcc support
-    result = obj.send_with(
+    result = obj.send_email(
         'template_id',
         { name: 'Matt', address: 'recipient@example.com' },
-        { company_name: 'TestCo' },
-        { name: 'Company',
+        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',
@@ -87,16 +93,16 @@ begin
     puts result
 
     # Attachment support
-    result = obj.send_with(
+    result = obj.send_email(
         'template_id',
         { name: 'Matt', address: 'recipient@example.com' },
-        { company_name: 'TestCo' },
-        { name: 'Company',
+        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') },
@@ -107,17 +113,71 @@ begin
 
     # Set ESP account
     # See: https://help.sendwithus.com/support/solurtions/articles/1000088976-set-up-and-use-multiple
-    result = obj.send_with(
+    result = obj.send_email(
         'template_id',
         { name: 'Matt', address: 'recipient@example.com' },
-        { company_name: 'TestCo' },
-        { name: 'Company',
+        data: { company_name: 'TestCo' },
+        from: { name: 'Company',
             address: 'company@example.com',
             reply_to: 'info@example.com' },
-        [],
-        [],
-        [],
-        'esp_MYESPACCOUNT')
+        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}"

data/lib/send_with_us/api.rb

@@ -23,41 +23,104 @@ module SendWithUs
       @configuration = SendWithUs::Config.new(settings)
     end
 
-    def send_with(email_id, to, data = {}, from = {}, cc = {}, bcc = {}, files = [], esp_account = '', version_name = '', headers = {}, tags = [])
+    # DEPRECATED: Please use 'send_email' instead.
+    #
+    # Sends the specified email with any arguments.
+    #
+    # * *Args*    :
+    #   - +email_id+ -> ID of the email to send
+    #   - +to+ -> Hash of recipient details
+    #   - +data+ -> Hash of email data
+    #   - +from+ -> Hash of sender details
+    #   - +cc+ -> Array of CC recipients
+    #   - +bcc+ -> Array of BCC recipients
+    #   - +files+ -> Array of attachments
+    #   - +esp_account+ -> The ESP account to use
+    #   - +version_name+ -> The specific email version to use
+    #   - +headers+ -> Hash of headers
+    #   - +tags+ -> Array of tags
+    # * *Notes*    :
+    #   - "send" is already a ruby-defined method on all classes
+    #
+    def send_with(email_id, to, data = {}, from = {}, cc = [], bcc = [], files = [], esp_account = '', version_name = '', headers = {}, tags = [])
+      warn "[DEPRECATED] 'send_with' is deprecated.  Please use 'send_email' instead."
+
+      send_email(
+        email_id,
+        to,
+        data: data,
+        from: from,
+        cc: cc,
+        bcc: bcc,
+        files: files,
+        esp_account: esp_account,
+        version_name: version_name,
+        headers: headers,
+        tags: tags
+      )
+    end
 
+    # Sends the specified email with any optional arguments
+    #
+    # * *Args*    :
+    #   - +email_id+ -> ID of the email to send
+    #   - +to+ -> Hash of recipient details
+    # * *Options*    :
+    #   - +:data+ -> Hash of email data
+    #   - +:from+ -> Hash of sender details
+    #   - +:cc+ -> Array of CC recipients
+    #   - +:bcc+ -> Array of BCC recipients
+    #   - +:files+ -> Array of attachments
+    #   - +:esp_account+ -> The ESP account to use
+    #   - +:version_name+ -> The specific email version to use
+    #   - +:headers+ -> Hash of headers
+    #   - +:tags+ -> Array of tags
+    #   - +:locale+ -> Localization string
+    # * *Notes*    :
+    #   - "send" is already a ruby-defined method on all classes
+    #
+    def send_email(email_id, to, options = {})
       if email_id.nil?
         raise SendWithUs::ApiNilEmailId, 'email_id cannot be nil'
       end
 
-      payload = { email_id: email_id, recipient: to,
-                  email_data: data }
+      payload = {
+        email_id: email_id,
+        recipient: to
+      }
 
-      if from.any?
-        payload[:sender] = from
+      if options[:data] && options[:data].any?
+        payload[:email_data] = options[:data]
       end
-      if cc.any?
-        payload[:cc] = cc
+      if options[:from] && options[:from].any?
+        payload[:sender] = options[:from]
       end
-      if bcc.any?
-        payload[:bcc] = bcc
+      if options[:cc] && options[:cc].any?
+        payload[:cc] = options[:cc]
       end
-      if esp_account
-        payload[:esp_account] = esp_account
+      if options[:bcc] && options[:bcc].any?
+        payload[:bcc] = options[:bcc]
       end
-      if version_name
-        payload[:version_name] = version_name
+      if options[:esp_account]
+        payload[:esp_account] = options[:esp_account]
       end
-      if headers.any?
-        payload[:headers] = headers
+      if options[:version_name]
+        payload[:version_name] = options[:version_name]
       end
-      if tags.any?
-        payload[:tags] = tags
+      if options[:headers] && options[:headers].any?
+        payload[:headers] = options[:headers]
+      end
+      if options[:tags] && options[:tags].any?
+        payload[:tags] = options[:tags]
+      end
+      if options[:locale]
+        payload[:locale] = options[:locale]
       end
 
-      if files.any?
+      if options[:files] && options[:files].any?
         payload[:files] = []
 
-        files.each do |file_data|
+        options[:files].each do |file_data|
           if file_data.is_a?(String)
             attachment = SendWithUs::Attachment.new(file_data)
           else
@@ -68,18 +131,18 @@ module SendWithUs
       end
 
       payload = payload.to_json
+      puts payload
       SendWithUs::ApiRequest.new(@configuration).post(:send, payload)
     end
 
     def drips_unsubscribe(email_address)
-
       if email_address.nil?
         raise SendWithUs::ApiNilEmailId, 'email_address cannot be nil'
       end
 
-      payload = { email_address: email_address }
-      payload = payload.to_json
+      payload = {email_address: email_address}
 
+      payload = payload.to_json
       SendWithUs::ApiRequest.new(@configuration).post(:'drips/unsubscribe', payload)
     end
 
@@ -92,9 +155,12 @@ module SendWithUs
         template_id: template_id,
         template_data: template_data,
       }
-      payload[:version_id] = version_id if version_id
-      payload = payload.to_json
 
+      if version_id
+        payload[:version_id] = version_id
+      end
+
+      payload = payload.to_json
       SendWithUs::ApiRequest.new(@configuration).post(:'render', payload)
     end
 
@@ -104,8 +170,9 @@ module SendWithUs
         subject: subject,
         html: html,
         text: text
-      }.to_json
+      }
 
+      payload = payload.to_json
       SendWithUs::ApiRequest.new(@configuration).post(:emails, payload)
     end
 
@@ -113,27 +180,27 @@ module SendWithUs
       SendWithUs::ApiRequest.new(@configuration).get(:drip_campaigns)
     end
 
-    def start_on_drip_campaign(recipient_address, drip_campaign_id, email_data={})
+    def start_on_drip_campaign(recipient_address, drip_campaign_id, email_data={}, locale=nil)
+      payload = {recipient_address: recipient_address}
 
-      if email_data.nil?
-        payload = {
-          recipient_address: recipient_address
-        }.to_json
-      else
-        payload = {
-          recipient_address: recipient_address,
-          email_data: email_data
-        }.to_json
+      if email_data && email_data.any?
+        payload[:email_data] = email_data
+      end
+      if locale
+        payload[:locale] = locale
       end
 
-      SendWithUs::ApiRequest.new(@configuration).post("drip_campaigns/#{drip_campaign_id}/activate", payload)
+      payload = payload.to_json
+      endpoint = "drip_campaigns/#{drip_campaign_id}/activate"
+      SendWithUs::ApiRequest.new(@configuration).post(endpoint, payload)
     end
 
     def remove_from_drip_campaign(recipient_address, drip_campaign_id)
       payload = {
         recipient_address: recipient_address
-      }.to_json
+      }
 
+      payload = payload.to_json
       SendWithUs::ApiRequest.new(@configuration).post("drip_campaigns/#{drip_campaign_id}/deactivate", payload)
     end
 
@@ -149,27 +216,29 @@ module SendWithUs
       SendWithUs::ApiRequest.new(@configuration).get("drip_campaigns/#{drip_campaign_id}/step/#{drip_campaign_step_id}/customers")
     end
 
-    # DEPRECATED - use customer_conversion now
+    # DEPRECATED: Please use 'customer_conversion' instead.
     def add_customer_event(customer, event_name, revenue=nil)
+      warn "[DEPRECATED] 'add_customer_event' is deprecated.  Please use 'customer_conversion' instead."
+
+      payload = {event_name: event_name}
 
-      if revenue.nil?
-        payload = { event_name: event_name }
-      else
-        payload = { event_name: event_name, revenue: revenue}
+      if revenue
+        payload[:revenue] = revenue
       end
 
       payload = payload.to_json
-      endpoint = 'customers/' + customer + '/conversions'
+      endpoint = "customers/#{customer}/conversions"
       SendWithUs::ApiRequest.new(@configuration).post(endpoint, payload)
     end
 
     def customer_conversion(customer, revenue=nil)
-      payload = {}.to_json
+      payload = {}
 
       if revenue
-        payload = { revenue: revenue }.to_json
+        payload[:revenue] = revenue
       end
 
+      payload = payload.to_json
       endpoint = "customers/#{customer}/conversions"
       SendWithUs::ApiRequest.new(@configuration).post(endpoint, payload)
     end
@@ -177,16 +246,18 @@ module SendWithUs
     def customer_create(email, data = {})
       payload = {email: email}
 
-      if data.any?
+      if data && data.any?
         payload[:data] = data
       end
 
       payload = payload.to_json
-      SendWithUs::ApiRequest.new(@configuration).post("customers", payload)
+      endpoint = "customers"
+      SendWithUs::ApiRequest.new(@configuration).post(endpoint, payload)
     end
 
     def customer_delete(email)
-      SendWithUs::ApiRequest.new(@configuration).delete("customers/#{email}")
+      endpoint = "customers/#{email}"
+      SendWithUs::ApiRequest.new(@configuration).delete(endpoint)
     end
   end
 end

data/lib/send_with_us/version.rb

@@ -1,3 +1,3 @@
 module SendWithUs
-  VERSION = '1.8.0'
+  VERSION = '1.9.0'
 end

data/test/lib/send_with_us/api_request_test.rb

@@ -17,21 +17,6 @@ class TestApiRequest < MiniTest::Unit::TestCase
     assert_instance_of( Net::HTTPSuccess, @request.post(:send, @payload) )
   end
 
-  def test_attachment
-    build_objects
-    email_id = 'test_fixture_1'
-    result = @api.send_with(
-      email_id,
-      {name: 'Ruby Unit Test', address: 'matt@example.com'},
-      {name: 'sendwithus', address: 'matt@example.com'},
-      {},
-      [],
-      [],
-      ['README.md']
-    )
-    assert_instance_of( Net::HTTPOK, result )
-  end
-
   def test_unsubscribe
     build_objects
     Net::HTTP.any_instance.stubs(:request).returns(Net::HTTPSuccess.new(1.0, 200, "OK"))
@@ -68,14 +53,29 @@ class TestApiRequest < MiniTest::Unit::TestCase
     assert_raises( SendWithUs::ApiConnectionRefused ) { @request.post(:send, @payload) }
   end
 
-  def test_send_with_version
+  def test_send_with_with_attachment
+    build_objects
+    email_id = 'test_fixture_1'
+    result = @api.send_with(
+      email_id,
+      {name: 'Ruby Unit Test', address: 'matt@example.com'},
+      {data: 'I AM DATA'},
+      {name: 'sendwithus', address: 'matt@example.com'},
+      [],
+      [],
+      ['README.md']
+    )
+    assert_instance_of( Net::HTTPOK, result )
+  end
+
+  def test_send_with_with_version
     build_objects
     email_id = 'tem_9YvYsaLW2Mw4tmPiLcVvpC'
     result = @api.send_with(
       email_id,
       {name: 'Ruby Unit Test', address: 'matt@example.com'},
+      {data: 'I AM DATA'},
       {name: 'sendwithus', address: 'matt@example.com'},
-      {},
       [],
       [],
       [],
@@ -85,14 +85,14 @@ class TestApiRequest < MiniTest::Unit::TestCase
     assert_instance_of( Net::HTTPOK, result )
   end
 
-  def test_send_with_headers
+  def test_send_with_with_headers
     build_objects
     email_id = 'tem_9YvYsaLW2Mw4tmPiLcVvpC'
     result = @api.send_with(
       email_id,
       {name: 'Ruby Unit Test', address: 'matt@example.com'},
+      {data: 'I AM DATA'},
       {name: 'sendwithus', address: 'matt@example.com'},
-      {},
       [],
       [],
       [],
@@ -103,14 +103,14 @@ class TestApiRequest < MiniTest::Unit::TestCase
     assert_instance_of( Net::HTTPOK, result )
   end
 
-  def test_send_with_tags
+  def test_send_with_with_tags
     build_objects
     email_id = 'tem_9YvYsaLW2Mw4tmPiLcVvpC'
     result = @api.send_with(
       email_id,
       {name: 'Ruby Unit Test', address: 'matt@example.com'},
+      {data: 'I AM DATA'},
       {name: 'sendwithus', address: 'matt@example.com'},
-      {},
       [],
       [],
       [],
@@ -122,6 +122,35 @@ class TestApiRequest < MiniTest::Unit::TestCase
     assert_instance_of( Net::HTTPOK, result )
   end
 
+  def test_send_with_tags
+    build_objects
+    email_id = 'tem_9YvYsaLW2Mw4tmPiLcVvpC'
+    result = @api.send_email(
+      email_id,
+      {name: 'Ruby Unit Test', address: 'matt@example.com'},
+      data: {data: 'I AM DATA'},
+      from: {name: 'sendwithus', address: 'matt@example.com'},
+      version_name: 'v2',
+      tags: ['tag1', 'tag2']
+    )
+    assert_instance_of( Net::HTTPOK, result )
+  end
+
+  def test_send_with_locale
+    build_objects
+    email_id = 'tem_9YvYsaLW2Mw4tmPiLcVvpC'
+    result = @api.send_email(
+      email_id,
+      {name: 'Ruby Unit Test', address: 'matt@example.com'},
+      data: {data: 'I AM DATA'},
+      from: {name: 'sendwithus', address: 'matt@example.com'},
+      version_name: 'v2',
+      tags: ['tag1', 'tag2'],
+      locale: 'en-US'
+    )
+    assert_instance_of( Net::HTTPOK, result )
+  end
+
   def test_render
     build_objects
     email_id = 'tem_9YvYsaLW2Mw4tmPiLcVvpC'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: send_with_us
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
   prerelease: 
 platform: ruby
 authors:
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-06 00:00:00.000000000 Z
+date: 2015-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake