readme.md

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:

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.

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 => 'igor@example.com' }.
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:

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.