mailhandler

MailHandler Gem

MailHandler is a simple wrapper on top of Mail gem and Postmark gem libraries. It allows you to send and retrieve emails and at the same time get details on how long these operations took. Main purpose of the gem is easier email sending/delivery testing with notification option if sending or retrieving email is taking too long.

The library supports sending email by standard SMTP protocol and by Postmark API. More importantly it also allows checking email delivery by IMAP protocol, or by folder if you have a local mailbox.

Install the gem

With Bundler:

gem 'mailhandler'

Without Bundler:

gem install mailhandler

Email retrieval

Configure local folder as your mailbox check for emails

Searching emails locally is an option that can be used when you have emails stored in certain local path on your test machine. In order to search for email, all you need to do is setup inbox folder and archive folder.

Folders can be the same if you don't plan to archive found emails. Retrieving emails from a folder would look like following:

inbox_folder = '/folder/mailbox/inbox'
archive_folder = '/folder/mailbox/archive/'

email_receiver = MailHandler.receiver(:folder) do |checker|
    checker.inbox_folder = inbox_folder
    checker.archive_folder = archive_folder
end

Configure imap mailbox email to check

If you plan to search for emails in your remote inbox which supports IMAP, you can use Mailhandler by providing IMAP settings. We recommend to keep credentials for your IMAP settings safe, and read them from config file or environment variables. Do NOT keep credentials in your repositories.

address = 'imap.example.com'
port = 993
username = 'john'
password = 'xxxxxxxxxxxxxx'
use_ssl = true

email_receiver = MailHandler.receiver(:imap) do |checker|
  checker.address = address
  checker.port = port
  checker.username = username
  checker.password = password
  checker.use_ssl  =  use_ssl
end

Email receiving handler will be referenced in examples below as email_receiver.

Searching for email

Once you have setup mailbox searching type, you can search for email like this:

email_receiver.find_email(:by_subject => subject, :archive => true)

You can search imap mailbox by following options:

• :by_subject - subject of the email
• :by_content - search email content by keywords
• :by_recipient - by email recipient

You can search local mailbox by following options:

• :by_subject - subject of the email
• :by_recipient - by email recipient
• :by_content - search email content by keywords

Recipient to search by needs to by added in the following form: by_recipient => { :to => '[e-mail]' }. Library supports searching by :to, :cc recipients. At the moment, only searching by a single recipient email address is supported.

If you would like email to be archived after its read, use :archive => true option (recommended).

For now, Unicode is not supported for search by local mailbox, only ASCII.

Search results

Once email searching is finished, you can check search results by checking: email_receiver.search object, which has following information:

• :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 - first email found in search
• :emails - array of all emails found in search

Email search notifications

While searching for an email, there is a possibility to get notification if emails searching is taking too long. You can get an notification in console, by email or both.

Console notification is a good option if you are testing email delivery and want to see console output on how is the progress of search going.

To add console or email notifications, to your email searching all you need to do is:

email_receiver.add_observer(MailHandler::Receiving::Notification::Email.new(email_sender, from, contacts))
email_receiver.add_observer(MailHandler::Receiving::Notification::Console.new)

For email notifications, the parameters you need are:

• email_sender - email sender you will use for sending an email (it should be one of senders described below)
• from - email address from which email is sent
• contacts - list of contacts to receive the notification (for example: [e-mail], [e-mail]

Email sending

There are three ways you can send email, which we will describe below. To send email you can use SMTP protocol or Postmark API.

Send by Postmark API

To send email with Postmark, you need to choose type of sending, api token options.

api_token = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

email_sender = MailHandler.sender(type) do |dispatcher|
    dispatcher.api_token = api_token
end

• :type - type can be :postmark_api or :postmark_batch_api
• :api_token - api token of one of your Postmark sending servers

Sending email by SMTP

To send email with SMTP you need to configure standard SMTP settings. We recommend to keep credentials for your SMTP settings safe, and read them from config file or environment variables. Do NOT keep credentials in your repositories.

address = 'imap.example.com'
domain = 'example.com'
port = 587
username = 'john'
password = 'xxxxxxxxxxxxxx'
use_ssl = true

email_sender = MailHandler.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 email

Once you have setup your email sender, all you need to do is to send an email:

email_sender.send_email(email)

Email you plan to send has to be an email created with Mail gem. In order to send emails by Postmark batch, you will need to provide an Array of emails.

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

License

MailHandler Library is licensed under the MIT license. Refere to the LICENSE file for more information.