mailhandler 1.0.1

data/lib/mailhandler/sender.rb

@@ -0,0 +1,56 @@
+require_relative 'sending/sender_smtp'
+require_relative 'sending/sender_api'
+require_relative 'sending/sender_api_batch'
+
+module MailHandler
+
+  class Sender
+
+    attr_accessor :dispatcher,
+                  :sending
+
+    # @param [Time] - sending started at Time
+    # @param [Time] - sending finished at Time
+    # @param [int] - how long sending lasted
+    # @param [Object] - sending response message
+    # @param [Mail] - email/emails sent
+    Sending = Struct.new( :started_at, :finished_at, :duration, :response, :email)
+
+    def initialize(dispatcher)
+
+      @dispatcher = dispatcher
+      @sending = Sending.new
+
+    end
+
+    def send_email(email)
+
+      init_sending_details(email)
+      response = dispatcher.send(email)
+      update_sending_details(response)
+
+      response
+
+    end
+
+    private
+
+    def init_sending_details(email)
+
+      @sending = Sending.new
+      @sending.started_at = Time.now
+      @sending.email = email
+
+    end
+
+    def update_sending_details(response)
+
+      @sending.finished_at = Time.now
+      @sending.duration = @sending.finished_at - @sending.started_at
+      @sending.response = response
+
+    end
+
+  end
+
+end

data/lib/mailhandler/sending/sender.rb

@@ -0,0 +1,13 @@
+module MailHandler
+
+  module Sending
+
+    class Sender
+
+      attr_reader :type
+
+    end
+
+  end
+
+end

data/lib/mailhandler/sending/sender_api.rb

@@ -0,0 +1,45 @@
+require 'mail'
+require 'postmark'
+require_relative 'sender.rb'
+
+module MailHandler
+
+  module Sending
+
+    class PostmarkAPISender < Sender
+
+      attr_accessor :host,
+                    :api_token,
+                    :use_ssl
+
+      def initialize(host = nil, api_token = nil, use_ssl = false)
+
+        @type = :postmark_api
+        @host = host
+        @api_token = api_token
+        @use_ssl = use_ssl
+
+      end
+
+      def send(email)
+
+        client = setup_sending_client
+        client.deliver_message(email)
+
+      end
+
+      protected
+
+      def setup_sending_client
+
+        # clearing cache so valid host is accepted, and not the cached one
+        Postmark::HttpClient.instance_variable_set('@http', nil)
+        Postmark::ApiClient.new(api_token, http_open_timeout: 15, host: host, secure: @use_ssl)
+
+      end
+
+    end
+
+  end
+
+end

data/lib/mailhandler/sending/sender_api_batch.rb

@@ -0,0 +1,20 @@
+require_relative 'sender_api.rb'
+
+module MailHandler
+
+  module Sending
+
+    class PostmarkBatchAPISender < PostmarkAPISender
+
+      def send(emails)
+
+        client = setup_sending_client
+        client.deliver_messages(emails)
+
+      end
+
+    end
+
+  end
+
+end

data/lib/mailhandler/sending/sender_smtp.rb

@@ -0,0 +1,76 @@
+# encoding: utf-8
+require 'net/imap'
+require_relative 'sender'
+
+module MailHandler
+
+  module Sending
+
+    # class which describes methods to send and receive emails
+    class SMTPSender < Sender
+
+      # address - for smtp for example smtp.gmail.com
+      # port which would be used for sending
+      # domain for example for smtp.gmail.com it would be gmail.com
+      attr_accessor :address,
+                    :port,
+                    :domain,
+                    :username,
+                    :password,
+                    :authentication,
+                    :use_ssl
+
+      def initialize
+
+        @type = :smtp
+        @authentication = 'plain'
+        @use_ssl = false
+
+      end
+
+      def send(email)
+
+        email = configure_sending(email)
+
+        response = nil
+
+        begin
+
+          response = email.deliver
+
+        rescue Exception => e
+
+          response = e.to_s
+
+        end
+
+        response
+
+      end
+
+      private
+
+      def configure_sending(email)
+
+        options = {
+
+            :address => address,
+            :port => port,
+            :domain => domain,
+            :user_name => username,
+            :password => password,
+            :authentication => @authentication,
+            :enable_starttls_auto => @use_ssl
+
+        }
+
+        email.delivery_method :smtp, options
+        email
+
+      end
+
+    end
+
+  end
+
+end

data/lib/mailhandler/version.rb

@@ -0,0 +1,5 @@
+module MailHandler
+
+  VERSION = '1.0.1'
+
+end

data/mailhandler.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'mailhandler/version'
+
+Gem::Specification.new do |s|
+
+  s.name        = 'mailhandler'
+  s.version     = MailHandler::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.license     = 'MIT'
+
+  s.authors     = ["Igor Balos"]
+  s.email       = "ibalosh@gmail.com"
+
+  s.summary     = "Postmark email receiving and sending handler."
+  s.description = "Use this gem to send emails through SMTP and Postmark API. Check if email arrived by imap or folder check."
+
+
+  s.files       = `git ls-files`.split($/)
+  s.homepage    = 'https://github.com/ibalosh'
+  s.require_paths = ["lib"]
+  s.required_rubygems_version = ">= 1.8.7"
+
+  s.add_dependency "mail"
+  s.add_dependency "postmark", '~> 1.7.0','>= 1.7.0'
+
+end

data/readme.md

@@ -0,0 +1,151 @@
+# MailHandler Gem
+
+This gem represents a simple library which allows you to send email and check email delivery. 
+The library supports sending SMTP, Postmark API or Postmark Batch API, checking email delivery by IMAP, or by folder, 
+if you have a local mailbox. 
+
+# Install the gem
+
+With Bundler:
+
+``` ruby
+gem 'mailhandler'
+``` 
+
+Without Bundler:
+
+``` bash
+gem install mailhandler
+``` 
+
+# Email arrival testing 
+
+## Configure local mailbox email to check
+
+``` ruby
+email_receiver = MailHandler::Handler.receiver(:folder) do |checker|
+    checker.inbox_folder = folder_of_your_inbox
+    checker.archive_folder = folder_of_your_inbox_archive_folder
+end
+```  
+
+## Configure imap mailbox email to check
+ 
+``` ruby
+email_receiver = MailHandler::Handler.receiver(:imap) do |checker|
+    checker.imap_details(
+        address,
+        port,
+        username,
+        password,
+        use_ssl
+    )
+end
+``` 
+Email receiving handler will be referenced below as `email_receiver`
+
+## Searching for email
+
+Once you have setup mailbox checking type, you can search for email like this:
+
+``` ruby
+email_receiver.find_email(:by_subject => email.subject, :archive => true)
+``` 
+
+You can search imap mailbox by following options:
+
+* `:by_subject` - subject of the email
+
+You can search local mailbox by following options:
+
+* `:by_subject` - subject of the email   
+* `:by_recipient` - by email recipient
+
+If you would like email to be archived after its read, use `:archive => true` option (recommended)
+
+## Search results
+
+Once email searching is finished, you can check search result by looking at: `email_receiver.search` object
+
+* `:options` - search options which were used (described above)
+* `:started_at` - time when search was initiated
+* `:finished_at` - time when search was stopped
+* `:duration` - time how long the search took 
+* `:max_duration` - maximum amount of time search can take in seconds (default is 240)
+* `:result - result of search - `true/false`
+* `:email` - email found in search 
+* `:emails` - array of emails found in search
+
+# Email search notifications
+
+While searching for an email, there is a possibility to get notification if emails sending is taking too long. 
+You can get an notification in console, by email or both.
+
+To add notifications to email searching all you need to do is:
+
+``` ruby
+email_receiver.add_observer(MailHandler::Receiving::Notification::Email.new(email_sender, contacts))
+email_receiver.add_observer(MailHandler::Receiving::Notification::Console.new)
+``` 
+
+the parameters you need are:
+
+* `email_sender` - email sender you will use for sending an email (it should be one of senders described below)
+* `contacts` - list of contacts to receive the notification (for example: `john@example.com, igor@example.com`
+ 
+# Email sending 
+
+There are three ways you can send email. 
+ 
+## Send by postmark
+
+To send email you can use SMTP protocol or Postmark.
+
+### Send by Postmark API 
+
+To send email with Postmark, you need to choose type of sending, host, api token, and ssl options.
+ 
+``` ruby
+email_sender = MailHandler::Handler.sender(type) do |dispatcher|
+    dispatcher.host = host
+    dispatcher.api_token = api_token
+    dispatcher.use_ssl = use_ssl
+end
+```
+
+* `:type` - type can be `:postmark_api` or `postmark_batch_api`
+* `:host` - host is `api.postmarkapp.com`
+* `:api_token` - api token of one of your Postmark sending servers 
+* `:use_ssl` - can be true/false
+  
+### Sending email by SMTP
+
+To send email with SMTP you need to configure standard SMTP settings.
+
+``` ruby
+email_sender = MailHandler::Handler.sender(:smtp) do |dispatcher|
+    dispatcher.address = address
+    dispatcher.port = port
+    dispatcher.domain = domain
+    dispatcher.username = username
+    dispatcher.password = password
+    dispatcher.use_ssl = use_ssl
+end
+``` 
+
+## Sending results
+ 
+Once email sending is finished, you can check sending result by looking at: `email_receiver.sending` object 
+
+* `:started_at` - time when sending was initiated
+* `:finished_at` - time when sending was finished
+* `:duration` - time how long the sending took 
+* `:response` - response from sending
+* `:email` - email sent
+ 
+
+
+
+
+
+

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: mailhandler
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Igor Balos
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-10-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: postmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+description: Use this gem to send emails through SMTP and Postmark API. Check if email
+  arrived by imap or folder check.
+email: ibalosh@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- lib/mailhandler.rb
+- lib/mailhandler/receiver.rb
+- lib/mailhandler/receiving/checker.rb
+- lib/mailhandler/receiving/checker_folder.rb
+- lib/mailhandler/receiving/checker_imap.rb
+- lib/mailhandler/receiving/filter.rb
+- lib/mailhandler/receiving/notification/console.rb
+- lib/mailhandler/receiving/notification/email.rb
+- lib/mailhandler/receiving/notification/email/content.rb
+- lib/mailhandler/receiving/notification/email/states.rb
+- lib/mailhandler/receiving/observer.rb
+- lib/mailhandler/sender.rb
+- lib/mailhandler/sending/sender.rb
+- lib/mailhandler/sending/sender_api.rb
+- lib/mailhandler/sending/sender_api_batch.rb
+- lib/mailhandler/sending/sender_smtp.rb
+- lib/mailhandler/version.rb
+- mailhandler.gemspec
+- readme.md
+homepage: https://github.com/ibalosh
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.8.7
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Postmark email receiving and sending handler.
+test_files: []