jangosmtp 0.1.1

data/.gitignore

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

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in jangosmtp.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Brennon Loveless
+
+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,89 @@
+# Jangosmtp
+
+This gem will allow a user to easily incorporate jangosmtp into their existing rails project. This gem uses the jangosmtp api rather than the jangosmtp smtp relay since, according to the jangosmtp docs, the api is faster and more reliable than using the jangosmtp relay. Currently at our company we are only using the send and transaction group functions, but if you would like, feel free to make a request for more functions as well as forking this repo and submitting a new pull request. Please enjoy and I do apologize for not having any tests at this very moment.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'jangosmtp'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install jangosmtp
+
+## Configuration
+
+In your environment file there are a few options that you can pass to Jangosmtp as follows:
+
+After the gem is installed you will need to add your jango configuration to your environment file. Using the following lines of code. Pay close attention to the comments here.
+
+    Jangosmtp.options({
+      username: 'username',
+      password: 'password',
+      max_attempts: 1,
+      click_tracking: true,
+      open_tracking: true,
+      auto_generate_plain: true
+    })
+
+* `username` __is required__ and is the same username you use to login to jangosmtp.
+* `password` __is required__ and is the same password you use to login to jangosmtp.
+* `max_attempts` is __not required__, but if there is a failed call to jangosmtp the gem will attempt the try again every three seconds until max_attempts is reached. There is a catch here, jangosmtp relies on 500 internal server errors even when a value is listed incorrectly, so this will slow down your application. For example: when creating a groups this gem tries to get the group first. If jangosmtp does not find the requested group then it will throw a 500 internal server error. Which will cause the system to try again until the max number of attempts are reached before attempting to create the group. I'm working with jangosmtp for a fix to this issue.
+* `click_tracking` is __not required__ but will default to true which enables tracking for whenever anyone clicks on any link that is included in your email.
+* `open_tracking` is __not required__ but will default to true which enables tracking for whenever anyone opens an email you sent, this is done by jangosmtp including a transparent image in your email so they can monitor when the image is downloaded from their server.
+* `auto_generate_plain` is __not required__ but will default to true which tells jangosmtp that you are sending html content for your email and that jangosmtp should generate the plain text version of the email to be sent along with your email, this is recommended since this gem doesn't currently have the ability to send plain text emails
+
+## Usage
+
+### Get and/or create group
+Get a group if the group exists, otherwise create a group using a group name and return it's id  
+`group_name`: group name that the user wants to get the id for, should only contain alphanumeric ( and spaces ) will be cleaned if an incorrect name is used
+    
+    get_create_group( group_name )
+    
+### Get group id
+Get the id of a requested group  
+`group_name`: group name that the user wants to get the id for, should only contain alphanumeric ( and spaces ) will be cleaned if an incorrect name is used
+
+    get_group_id( group_name )
+
+### Create group
+Create a group and return the successfull value  
+`group_name`: group name that the user wants to get the id for, should only contain alphanumeric ( and spaces ) will be cleaned if an incorrect name is used
+
+    create_group( group_name )
+
+### Send an email using group name
+Send an email and get/create a requested group  
+`group_name`: group name that the user wants the email to be applied to, should only contain alphanumeric ( and spaces ) will be cleaned if an incorrect name is used  
+`to_email`: the single email address that the email will be sent to  
+`from_email`: the email address that the email will be coming from  
+`from_name`: the name that the email address will be coming from  
+`html`: the html of the email message to be sent  
+  
+___IMPORTANT___: This function will attempt to get or create a group for each email that is sent. If you will be sending a lot of emails to the same group I would recommend you create the group first and use the `send_email_with_group_id` function since that takes a group_id and won't attempt to create the group with each email that is sent
+
+    send_email( group_name, to_email, from_email, from_name, html )
+
+### Send an email using group id
+Send an email using a pre-existing group  
+`group_id`: the id of the group that this email will be applied to  
+`to_email`: the single email address that the email will be sent to  
+`from_email`: the email address that the email will be coming from  
+`from_name`: the name that the email address will be coming from  
+`html`: the html of the email message to be sent  
+
+    send_email_with_group_id( group_id, to_email, from_email, from_name, html )
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/jangosmtp.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/jangosmtp/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Brennon Loveless"]
+  gem.email         = ["brennon@fritzandandre.com"]
+  gem.description   = %q{Library for interfacing with JangoSMTP}
+  gem.summary       = %q{Will encapsulate all the necessary api calls into an easy to use gem.}
+  gem.homepage      = "https://github.com/jbrennon/jangosmtp"
+  
+  gem.add_dependency 'mechanize'
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "jangosmtp"
+  gem.require_paths = ["lib"]
+  gem.version       = Jangosmtp::VERSION
+end

data/lib/jangosmtp.rb

@@ -0,0 +1,155 @@
+require 'jangosmtp/version'
+
+module Jangosmtp
+  
+  class << self
+    attr_accessor :username, :password, :max_attempts, :click_tracking, :open_tracking, :auto_generate_plain
+    BASE_URL = 'http://api.jangomail.com/api.asmx/'
+    
+    def options( hash )
+      @username = hash[:username] if !hash[:username].nil?
+      @password = hash[:password] if !hash[:password].nil?
+      @max_attempts = hash[:max_attempts] ||= 1
+      @click_tracking = hash[:click_tracking] ||= true
+      @open_tracking = hash[:open_tracking] ||= true
+      @auto_generate_plain = hash[:open_tracking] ||= true
+    end
+    
+    # Get a group if the group exists, otherwise create a group using a group name and return it's id
+    # group_name: group name that the user wants to get the id for, should only contain alphanumeric ( and spaces )
+    #   will be cleaned if an incorrect name is used
+    def get_create_group( group_name )
+      check_user_pass
+      existing_group_id = get_group_id( group_name )
+      if existing_group_id == nil
+        new_group_id = create_group( group_name )
+        return new_group_id
+      end
+      return existing_group_id
+    end
+    
+    # Get the id of a requested group
+    # group_name: group name that the user wants to get the id for, should only contain alphanumeric ( and spaces )
+    #   will be cleaned if an incorrect name is used
+    def get_group_id( group_name )
+      check_user_pass
+      # First we need to clean the group_name since jangosmtp only allows alphanumeric characters
+      group_name.tr!('^A-Za-z0-9 ', '')
+      options = {
+        'Username' => @username,
+        'Password' => @password,
+        'GroupName' => group_name
+      }
+    
+      # First we are going to check the existing groups to make sure that the current group doesn't already exist.
+      found_group = false
+      existing_group_id = nil
+      response = post_with_attempts( "GetTransactionalGroupID", options )
+      if response != false
+        existing_group_id = Nokogiri::XML.parse(response.body).xpath("*").first.content.split("\n")[2]
+        found_group = true
+      end
+    
+      return existing_group_id
+    end
+    
+    # Create a group and return the successfull value
+    # group_name: group name that the user wants to get the id for, should only contain alphanumeric ( and spaces )
+    #   will be cleaned if an incorrect name is used
+    def create_group( group_name )
+      check_user_pass
+      # First we need to clean the group_name since jangosmtp only allows alphanumeric characters
+      group_name.tr!('^A-Za-z0-9 ', '')
+      options = {
+        'Username' => @username,
+        'Password' => @password,
+        'GroupName' => group_name
+      }
+      
+      response = post_with_attempts( 'AddTransactionalGroup', options )
+      if response != false
+        new_group_id = Nokogiri::XML.parse(response.body).xpath("*").first.content.split("\n")[2]
+      end
+      return new_group_id
+    end
+    
+    # Send an email and get/create a requested group
+    # group_name: group name that the user wants the email to be applied to, should only contain alphanumeric
+    #   ( and spaces ) will be cleaned if an incorrect name is used
+    # to_email: the single email address that the email will be sent to
+    # from_email: the email address that the email will be coming from
+    # from_name: the name that the email address will be coming from
+    # html: the html of the email message to be sent
+    #
+    # IMPORTANT: This function will attempt to get or create a group for each email that is sent. If you will
+    #   be sending a lot of emails to the same group I would recommend you create the group first and use
+    #   the send_email_with_group_id function since that takes a group_id and won't attempt to create the
+    #   group with each email that is sent
+    def send_email( group_name, to_email, from_email, from_name, html )
+      check_user_pass
+      group_id = get_create_group( group_name )
+      unless group_id.nil?
+        return send_email_with_group_id( group_id, to_email, from_email, from_name, html )
+      end
+    end
+    
+    # Send an email using a pre-existing group
+    # group_id: the id of the group that this email will be applied to
+    # to_email: the single email address that the email will be sent to
+    # from_email: the email address that the email will be coming from
+    # from_name: the name that the email address will be coming from
+    # html: the html of the email message to be sent
+    def send_email_with_group_id( group_id, to_email, from_email, from_name, html )
+      check_user_pass
+      # Send the email using Jango
+      options = {
+        'Username' => @username,
+        'Password' => @password,
+        'FromEmail' => from_email,
+        'FromName' => from_name,
+        'ToEmailAddress' => to_email,
+        'Subject' => 'SOCO Authorization Request',
+        'MessagePlain' => 'auto-generate',
+        'MessageHTML' => html,
+        'Options' => 'OpenTrack=' + @open_tracking.to_s + ',ClickTrack=' + @click_tracking.to_s + ',TransactionalGroupID=' + group_id
+      }
+      return post_with_attempts( 'SendTransactionalEmail', options )
+    end
+    
+    private
+    # Will verify that the username and password exist for each request
+    def check_user_pass
+      if @username.nil? || @password.nil?
+        raise 'Jangosmtp username and password are required'
+      end
+    end
+    
+    # Will attempt to post to the jangosmtp action requested using the options hash passed in
+    def post_with_attempts( action, options )
+      agent = Mechanize.new
+      attempt = 0
+      response = false
+      # Try max_attempts times before skipping
+      while((attempt < max_attempts) && !response)
+        begin
+          response = agent.post( BASE_URL + action, options )
+        rescue StandardError => e
+          # If there was an error set success to false and try again in 3 seconds
+          response = false
+          attempt += 1
+          sleep 3
+        end
+      end
+      return response
+    end
+    
+    # Get either the Rails logger or the a logger to STDOUT
+    def logger
+      if !Rails.nil?
+        return Rails.logger
+      else
+        return Logger.new( STDOUT )
+      end
+    end
+  end
+end

data/lib/jangosmtp/version.rb

@@ -0,0 +1,3 @@
+module Jangosmtp
+  VERSION = "0.1.1"
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: jangosmtp
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+  prerelease: 
+platform: ruby
+authors:
+- Brennon Loveless
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-03-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mechanize
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Library for interfacing with JangoSMTP
+email:
+- brennon@fritzandandre.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- jangosmtp.gemspec
+- lib/jangosmtp.rb
+- lib/jangosmtp/version.rb
+homepage: https://github.com/jbrennon/jangosmtp
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.19
+signing_key: 
+specification_version: 3
+summary: Will encapsulate all the necessary api calls into an easy to use gem.
+test_files: []