emarsys-broadcast 0.1.0

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+test.rb

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - "1.9.2"
+  - "1.9.3"
+  - "2.0.0"
+  - "jruby-19mode"

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Valentin Vasilyev
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,284 @@
+# Emarsys::Broadcast
+
+Ruby wrapper for Emarsys batch mailing API
+==========================================
+[![Build Status](https://travis-ci.org/Valve/emarsys-broadcast-ruby.png)](https://travis-ci.org/Valve/emarsys-broadcast-ruby)
+[![Code Climate](https://codeclimate.com/github/Valve/emarsys-broadcast-ruby.png)](https://codeclimate.com/github/Valve/emarsys-broadcast-ruby)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'emarsys-broadcast'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install emarsys-broadcast
+
+## Usage
+
+### Complete sending example:
+
+Minimal configuration is required before usage
+
+```ruby
+# if using rails, place this configuration code into initializer
+Emarsys::Broadcast::configure do |c|
+  c.api_user = your_api_user
+  c.api_password = your_api_password
+
+  c.sftp_user = your_sftp_user
+  c.sftp_password = your_sftp_password
+
+  c.sender_domain = 'mail.your.company.com'
+end
+
+
+# create a batch that you want to send
+batch = Emarsys::Broadcast::Batch.new
+batch.sender = 'sender_id'
+batch.name = 'newsletter_2013_06_01'
+batch.subject = 'June 2013 company news'
+batch.body_html = '<h1>Dear 朋友!</h1>'
+batch.recipients_path = '/path/to/your/csv/with/emails'
+
+# create API client
+api = Emarsys::Broadcast::API.new
+
+# now send your batch
+api.send_batch(batch)
+```
+
+This will synchronously send the batch email to all recipients found in CSV file.
+
+### Moving batch properties to configuration
+
+If you find yourself using same batch attributes over and over again, for example `recipients_path`, 
+you can move those values into configuration:
+
+```ruby
+Emarsys::Broadcast::configure do |c|
+  c.api_user = your_api_user
+  c.api_password = your_api_password
+
+  c.sftp_user = your_sftp_user
+  c.sftp_password = your_sftp_password
+
+  c.sender = 'sender_id'
+  c.sender_domain = 'mail.your.company.com'
+  c.recipients_path = '/path/to/hyour/csv/with/emails'
+end
+
+# now you can omit these attributes when constructing a batch:
+batch = Emarsys::Broadcast::Batch.new
+batch.name = 'newsletter_2013_06_01'
+batch.subject = 'June 2013 company news'
+batch.body_html = '<h1>Dear 朋友!</h1>'
+
+# send your batch as above, via api
+```
+
+
+### Creating batch from hash
+
+If you like, you can construct your batch from a hash, like follows:
+
+```ruby
+batch = Emarsys::Broadcast::Batch.new name: 'name', subject: 'subject', body_html: '<h1>html body</h1>'
+```
+
+### Batch name requirements
+
+Batch name must be a valid identifier, i.e. start with a letter and contain letters, digits and underscores.
+Emarsys requires every batch to have a unique name, but you don't have to maintain the uniqueness, because
+this library internally appends a timestamp to each batch name before submitting it to Emarsys.
+
+### Batch subject requirements
+
+Batch subject must be a string with a maximum length of 255 characters
+
+### Batch body html 
+
+Batch body html can be any HTML text, no restrictions
+
+### Batch body in plain text
+
+It is possible to supply the body contents in plain text, this will broaden compatibility, 
+because some email clients don't support HTML and will download textual version instead.
+
+```ruby
+batch = Emarsys::Broadcast::Batch.new
+batch.name = 'newsletter_2013_06_01'
+batch.subject = 'June 2013 company news'
+batch.body_html = '<h1>Dear 朋友!</h1>'
+batch.body_text = 'Dear 朋友'
+```
+
+### Batch validation
+
+Emarsys::Broadcast uses ActiveModel for validating plain ruby objects, so you have all the methods for 
+validation you're accustomed to:
+
+```ruby
+batch = Emarsys::Broadcast::Batch.new
+batch.name = 'newsletter_2013_06_01'
+
+batch.valid? # false
+batch.errors 
+batch.errors.full_messages
+```
+
+You can always validate your batch before submitting it.
+
+Note that calling api#send_batch on an invalid batch will throw ValidationException
+
+```ruby
+batch = get_invalid_batch
+api = Emarsys::Broadcast::API.new
+begin
+  api.send_batch batch
+rescue Emarsys::Broadcast::ValidationException => ex
+  # get exception message
+  puts ex.message
+  # get exception errors (ActiveModel compatible)
+  puts ex.errors
+end
+```
+
+### CSV file requirements
+
+The recipients must be placed in a `UTF-8` CSV file.
+The file must have at least one column with `EMAIL` header, for example:
+
+```csv
+EMAIL
+john.doe@gmail.com
+sara.parker@yahoo.com
+...
+...
+```
+
+If you use additional customization columns, add them to your CSV file:
+
+```csv
+EMAIL FIRST_NAME
+john.doe@gmail.com John
+sara.parker@yahoo.com Sara
+...
+...
+```
+Having additional columns allows you to customize your body_html, for example:
+
+```html
+<h1>Hi, $$FIRST_NAME$$</h1>
+```
+
+### Batch sender_id requirements
+
+Emarsys requires that API users maintain a list of possible senders, and restricts
+sending emails from arbitrary sender.
+
+To use any `sender_id` in your batch, create it first:
+
+```ruby 
+# assuming you have API configured already
+api = Emarsys::Broadcast::API.new
+# sender requires 3 arguments: id, name, email_address
+sender = Emarsys::Broadcast::Sender.new('primary_newsletter_sender', 'My company', 'news@company.com')
+api.create_sender sender
+```
+
+Once you upload a sender, you can use its ID in any batch:
+
+```ruby
+batch.sender_id = 'primary_newsletter_sender'
+# more attributes
+```
+
+### Working with senders
+
+#### Getting a full list of senders
+
+```ruby
+api.get_senders 
+# returns Sender array
+```
+
+#### Getting a single sender by email
+
+```ruby 
+api.get_sender('news@mycompany.ru')
+```
+
+#### Find if a sender exists by email
+
+```ruby
+api.sender_exists? 'news@mycompany.ru'
+```
+
+### Scheduling batches
+
+By default a new batch is scheduled for immediate sending, but you can set the `send_time`
+
+```ruby
+# Assuming using ActiveSupport and want to schedule a batch to be sent in 10 days
+batch.send_time = Time.zone.now + 10.days
+# .. more attributes
+
+api.send_batch batch
+```
+
+### Compatibility
+
+This gem is tested on
+* MRI `1.9.2`, `1.9.3`, `2.0.0`
+* JRuby 1.9 mode
+
+
+### Further plans
+
+This library does not yet cover all Emarsys functionality, so the plans are to cover 100% of Emarsys features,
+add async support, more scheduling options etc. 
+
+If you want to help me with this, pull requests are especially welcome :)
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Run specs (`rspec`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create new Pull Request
+
+
+## License
+
+
+Copyright (c) 2013 Valentin Vasilyev
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+task(default: :spec)

data/emarsys-broadcast.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'emarsys/broadcast/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "emarsys-broadcast"
+  spec.version       = Emarsys::Broadcast::VERSION
+  spec.authors       = ["Valentin Vasilyev"]
+  spec.email         = ["iamvalentin@gmail.com"]
+  spec.description   = %q{Emarsys broadcast API for Ruby}
+  spec.summary       = %q{Emarsys broadcast API for Ruby}
+  spec.homepage      = "https://github.com/Valve/emarsys-broadcast-ruby"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "net-sftp"
+  spec.add_dependency "nokogiri"
+  spec.add_dependency "activemodel", "~> 3.0"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 2.11"
+  spec.add_development_dependency "timecop"
+  spec.add_development_dependency "webmock"
+end

data/lib/emarsys/broadcast/api.rb

@@ -0,0 +1,78 @@
+module Emarsys
+  module Broadcast
+    class API
+
+      def initialize
+        @config = Emarsys::Broadcast.configuration
+        @sftp = SFTP.new @config
+        @http = HTTP.new @config
+        @xml_builder = XmlBuilder.new
+      end
+
+      def send_batch(batch)
+        batch = supplement_batch_from_config(batch)
+        validate_batch(batch)
+        validate_sender(batch.sender)
+        create_batch(batch)
+        upload_recipients(batch.recipients_path)
+        trigger_import(batch)
+      end
+
+      def create_batch(batch)
+        emarsys_sender = get_sender(batch.sender)
+        batch.sender_id = emarsys_sender.id
+        batch_xml = BatchXmlBuilder.new.build(batch)
+        @http.post("#{@config.api_base_path}/batches/#{batch.name}", batch_xml)
+      end
+
+      def upload_recipients(recipients_path)
+        @sftp.upload_file(recipients_path, File.basename(recipients_path))
+      end
+
+      def trigger_import(batch)
+        import_xml = XmlBuilder.new.import_xml(File.basename(batch.recipients_path))
+        @http.post("#{@config.api_base_path}/batches/#{batch.name}/import", import_xml)
+      end
+
+      def get_senders
+        response = @http.get("#{@config.api_base_path}/senders")
+        Nokogiri::XML(response).xpath('//sender').map do |node|
+          Sender.new(node.attr('id'), node.xpath('name').text, node.xpath('address').text)
+        end
+      end
+
+      def get_sender(email)
+        get_senders.find{|s| s.address == email}
+      end
+
+      def create_sender(sender)
+        sender_xml = @xml_builder.sender_xml(sender)
+        @http.put("#{@config.api_base_path}/senders/#{sender.id}", sender_xml)
+      end
+
+      def sender_exists?(email)
+        get_senders.any?{|s|s.address == email}
+      end
+
+      private
+
+      def supplement_batch_from_config(batch)
+        batch.recipients_path ||= @config.recipients_path
+        batch.send_time ||= Time.now
+        batch.sender ||= @config.sender
+        batch.sender_domain ||= @config.sender_domain
+        batch
+      end
+
+      def validate_batch(batch)
+        raise ValidationError.new('Batch is invalid', batch.errors.full_messages) unless batch.valid?
+      end
+
+      def validate_sender(email)
+        msg = 'This email is not registered with Emarsys as a sender, register it with `create_sender` api call'
+        raise ValidationError, msg, [msg] unless sender_exists? email 
+      end
+    end
+    class ApiError < StandardError; end
+  end
+end

data/lib/emarsys/broadcast/batch.rb

@@ -0,0 +1,25 @@
+require 'uri'
+module Emarsys
+  module Broadcast
+    class Batch
+      include ActiveModel::Validations
+      attr_accessor \
+        :name, 
+        :subject,
+        :body_html,
+        :body_text,
+        :recipients_path,
+        :send_time,
+        :sender,
+        :sender_domain,
+        :sender_id
+
+        validates :name, :subject, :body_html, :recipients_path, :sender, :sender_domain, presence: true
+        validates :name, format: {with: /^[^\d\W]\w*\z/i, message: 'must start with a letter and contain only letters, numbers and underscores'}
+        validates :subject, length: {maximum: 255}
+        validates :sender, format: {with: /@/, message: 'is not a valid email'}
+        validates :sender_domain, format: {with: URI::REL_URI, message: 'is not valid'}
+
+    end
+  end
+end

data/lib/emarsys/broadcast/batch_xml_builder.rb

@@ -0,0 +1,34 @@
+require 'nokogiri'
+module Emarsys
+  module Broadcast
+    class BatchXmlBuilder
+
+      def build(batch)
+        raise ArgumentError, 'batch is required' unless batch
+        builder = Nokogiri::XML::Builder.new do |xml|
+          xml.batch {
+            xml.name batch.name
+            xml.runDate format_time(batch.send_time)
+            xml.properties {
+              xml.property(key: :Sender){xml.text batch.sender_id}
+              xml.property(key: :Language){xml.text 'en'}
+              xml.property(key: :Encoding){xml.text 'UTF-8'}
+              xml.property(key: :Domain){xml.text batch.sender_domain}
+            }
+            xml.subject batch.subject
+            xml.html batch.body_html
+            xml.text batch.body_text
+          }
+        end 
+        builder.to_xml
+      end
+
+
+      private 
+
+      def format_time(time)
+        time.strftime("%Y-%m-%dT%H:%M:%S%z")
+      end
+    end
+  end
+end

data/lib/emarsys/broadcast/configuration.rb

@@ -0,0 +1,43 @@
+module Emarsys
+  module Broadcast
+    class ConfigurationError < StandardError; end
+
+
+    class Configuration
+      attr_accessor \
+        :sftp_host, 
+        :sftp_user, 
+        :sftp_password, 
+        :sftp_port,
+        :api_host, 
+        :api_base_path,
+        :api_user, 
+        :api_password, 
+        :api_port,
+        :api_timeout,
+        :sender,
+        :sender_domain,
+        :recipients_path
+
+
+      def initialize
+        @sftp_host = 'e3.emarsys.net'
+        @sftp_port = 22
+        @api_host = 'e3.emarsys.net'
+        @api_base_path = '/bmapi/v2'
+        @api_port = 80
+        @api_timeout = 600 #10 minutes
+      end
+    end
+
+    class << self
+      attr_accessor :configuration
+    end
+
+    def self.configure
+      self.configuration ||= Configuration.new
+      yield configuration
+      configuration
+    end
+  end
+end

data/lib/emarsys/broadcast/email.rb

@@ -0,0 +1,11 @@
+module Emarsys
+  module Broadcast
+    module Email
+      REGEX = /\A(|(([A-Za-z0-9]+_+)|([A-Za-z0-9]+\-+)|([A-Za-z0-9]+\.+)|([A-Za-z0-9]+\++))*[A-Za-z0-9]+@((\w+\-+)|(\w+\.))*\w{1,63}\.[a-zA-Z]{2,6})\z/i
+
+      def self.validate(email)
+        email =~ REGEX
+      end
+    end
+  end
+end

data/lib/emarsys/broadcast/http.rb

@@ -0,0 +1,70 @@
+require 'net/http'
+module Emarsys
+  module Broadcast
+    class HTTP
+      include Validation
+
+      def initialize(config)
+        validate_config config
+        @config = config
+      end
+
+      def post(path, xml)
+        request(path, xml, :post)
+      end
+
+      def put(path, xml)
+        request(path, xml, :put)
+      end
+
+      def get(path)
+        request(path, nil, :get)
+      end
+
+
+      private
+
+      def request(path, data, method)
+        https = Net::HTTP.new(@config.api_host, Net::HTTP.https_default_port)
+        https.read_timeout = @config.api_timeout
+        https.use_ssl = true
+        https.verify_mode = OpenSSL::SSL::VERIFY_NONE
+
+        https.start do |http|
+          case method.downcase.to_sym
+          when :post
+            req = Net::HTTP::Post.new(path)
+          when :put
+            req = Net::HTTP::Put.new(path)
+          when :get
+            req = Net::HTTP::Get.new(path)
+          end
+          req.basic_auth(@config.api_user, @config.api_password)
+          req.body = data
+          req.content_type = "application/xml"
+
+          res = http.request(req)
+
+          case res
+          when Net::HTTPSuccess
+            puts "OK"
+            return res.body
+          else
+            puts res.body
+            res.error!
+          end
+        end
+      end
+
+      def validate_config(config)
+        raise ConfigurationError, 'configuration is nil, did you forget to configure the gem?' unless config
+        raise ConfigurationError, 'api_host must be configured' unless string_present? config.api_host
+        raise ConfigurationError, 'api_user must be configured' unless string_present? config.api_user
+        raise ConfigurationError, 'api_password must be configured' unless string_present? config.api_password
+        unless within_range? config.api_port, 1..65535
+          raise ConfigurationError, 'api_port must be integer between 1 and 65535' 
+        end
+      end
+    end
+  end
+end

data/lib/emarsys/broadcast/sender.rb

@@ -0,0 +1,11 @@
+module Emarsys
+  module Broadcast
+    class Sender
+      attr_reader :id, :name, :address
+
+      def initialize(id, name, address)
+        @id, @name, @address = id, name, address
+      end
+    end
+  end
+end

data/lib/emarsys/broadcast/sftp.rb

@@ -0,0 +1,31 @@
+require 'net/sftp'
+module Emarsys
+  module Broadcast
+    class SFTP
+      include Validation
+      
+      def initialize(config)
+        validate_config config
+        @config = config
+      end
+
+      def upload_file(local_path, remote_path)
+        Net::SFTP.start(@config.sftp_host, @config.sftp_user, password: @config.sftp_password) do |sftp|
+          sftp.upload!(local_path, remote_path)
+        end
+      end
+
+      private
+
+      def validate_config(config)
+        raise ConfigurationError, 'configuration is nil, did you forget to configure the gem?' unless config
+        raise ConfigurationError, 'sftp_host must be configured' unless string_present? config.sftp_host
+        raise ConfigurationError, 'sftp_user must be configured' unless string_present? config.sftp_user
+        raise ConfigurationError, 'sftp_password must be configured' unless string_present? config.sftp_password
+        unless within_range? config.sftp_port, 1..65535
+          raise ConfigurationError, 'sftp_port must be integer between 1 and 65535' 
+        end
+      end
+    end
+  end
+end