{"id":13631747,"url":"https://github.com/ActiveCampaign/mailhandler","last_synced_at":"2025-04-17T22:31:42.325Z","repository":{"id":56882594,"uuid":"47768839","full_name":"ActiveCampaign/mailhandler","owner":"ActiveCampaign","description":"Simple lightweight mail library which allows you to send and retrieve emails, and get more details about email sending and delivery","archived":false,"fork":false,"pushed_at":"2024-07-03T11:22:14.000Z","size":230,"stargazers_count":56,"open_issues_count":1,"forks_count":4,"subscribers_count":14,"default_branch":"main","last_synced_at":"2024-08-01T22:49:34.015Z","etag":null,"topics":["email-retrieval","postmark","qa","qatools"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ActiveCampaign.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-12-10T15:01:15.000Z","updated_at":"2024-07-03T11:22:17.000Z","dependencies_parsed_at":"2024-04-09T13:03:13.164Z","dependency_job_id":"7ac5ab7a-45e9-4900-9d24-69c5e9972387","html_url":"https://github.com/ActiveCampaign/mailhandler","commit_stats":{"total_commits":185,"total_committers":3,"mean_commits":"61.666666666666664","dds":0.05945945945945941,"last_synced_commit":"64287b498c277c907deed0933404b8f5c8f85dc0"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ActiveCampaign%2Fmailhandler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ActiveCampaign%2Fmailhandler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ActiveCampaign%2Fmailhandler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ActiveCampaign%2Fmailhandler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ActiveCampaign","download_url":"https://codeload.github.com/ActiveCampaign/mailhandler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223768652,"owners_count":17199356,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email-retrieval","postmark","qa","qatools"],"created_at":"2024-08-01T22:02:36.738Z","updated_at":"2024-11-08T23:31:33.246Z","avatar_url":"https://github.com/ActiveCampaign.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"\u003ca href=\"https://postmarkapp.com\"\u003e\n    \u003cimg src=\"postmark.png\" alt=\"Postmark Logo\" title=\"Postmark\" width=\"120\" height=\"120\" align=\"right\"\u003e\n\u003c/a\u003e\n\n# MailHandler Gem\n\n[![Build Status](https://circleci.com/gh/ActiveCampaign/mailhandler.svg?style=shield)](https://circleci.com/gh/ActiveCampaign/mailhandler)\n\nMailHandler is a simple wrapper on top of [Mail gem](https://github.com/mikel/mail) and [Postmark gem](https://github.com/ActiveCampaign/postmark-gem) libraries. It allows you to send and retrieve emails and at the same time get details on how long these operations took.\nMain purpose of the gem is easier email sending/delivery testing with notification option if sending or retrieving email is taking too long. \n\nThe 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. \n\n# Install the gem\n\nWith Bundler:\n\n``` ruby\ngem 'mailhandler'\n``` \n\nWithout Bundler:\n\n``` bash\ngem install mailhandler\n``` \n\n# Email retrieval  \n\n## Configure local folder as your mailbox check for emails\n\nSearching emails locally is an option that can be used when you have emails stored in certain local path on your test machine. \nIn order to search for email, all you need to do is setup inbox folder and archive folder. \n\nFolders can be the same if you don't plan to archive found emails. Retrieving emails from a folder would look like following:\n\n``` ruby\n\ninbox_folder = '/folder/mailbox/inbox'\narchive_folder = '/folder/mailbox/archive/'\n\nemail_receiver = MailHandler.receiver(:folder) do |checker|\n    checker.inbox_folder = inbox_folder\n    checker.archive_folder = archive_folder\nend\n```  \n\n## Configure imap mailbox email to check\n\nIf you plan to search for emails in your remote inbox which supports IMAP, you can use Mailhandler by providing IMAP settings.\nWe recommend to keep credentials for your IMAP settings safe, and read them from config file or environment variables.\nDo NOT keep credentials in your repositories. \n \n``` ruby\n\naddress = 'imap.example.com'\nport = 993\nusername = 'john'\npassword = 'xxxxxxxxxxxxxx'\nuse_ssl = true\n\nemail_receiver = MailHandler.receiver(:imap) do |checker|\n  checker.address = address\n  checker.port = port\n  checker.username = username\n  checker.password = password\n  checker.use_ssl  =  use_ssl\nend\n``` \n\nEmail receiving handler will be referenced in examples below as `email_receiver`.\n\n## Searching for email\n\nOnce you have setup mailbox searching type, you can search for email like this:\n\n``` ruby\nemail_receiver.find_email(:by_subject =\u003e subject, :archive =\u003e true)\n``` \n\nYou can search imap mailbox by following options:\n\n* `:by_subject` - subject of the email\n* `:by_content` - search email content by keywords\n* `:by_recipient` - by email recipient\n\nYou can search local mailbox by following options:\n\n* `:by_subject` - subject of the email   \n* `:by_recipient` - by email recipient\n* `:by_content` - search email content by keywords\n\nRecipient to search by needs to by added in the following form: `by_recipient =\u003e { :to =\u003e 'igor@example.com' }`.\nLibrary supports searching by :to, :cc recipients. At the moment, only searching by a single recipient email address is supported.\n\nIf you would like email to be archived after its read, use `:archive =\u003e true` option (recommended).\n\n**For now, Unicode is not supported for search by local mailbox, only ASCII.**\n\n## Search results\n\nOnce email searching is finished, you can check search results by checking: `email_receiver.search` object, which has following information:\n\n* `:options` - search options which were used (described above)\n* `:started_at` - time when search was initiated\n* `:finished_at` - time when search was stopped\n* `:duration` - time how long the search took \n* `:max_duration` - maximum amount of time search can take in seconds (default is 240)\n* `:result` - result of search - `true/false`\n* `:email` - first email found in search \n* `:emails` - array of all emails found in search\n\n# Email search notifications\n\nWhile searching for an email, there is a possibility to get notification if emails searching is taking too long. \nYou can get an notification in console, by email or both. \n\nConsole 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.\n\nTo add console or email notifications, to your email searching all you need to do is:\n\n``` ruby\nemail_receiver.add_observer(MailHandler::Receiving::Notification::Email.new(email_sender, from, contacts))\nemail_receiver.add_observer(MailHandler::Receiving::Notification::Console.new)\n``` \n\nFor email notifications, the parameters you need are:\n\n* `email_sender` - email sender you will use for sending an email (it should be one of senders described below)\n* `from` - email address from which email is sent \n* `contacts` - list of contacts to receive the notification (for example: `john@example.com, igor@example.com`\n \n# Email sending \n\nThere are three ways you can send email, which we will describe below. To send email you can use SMTP protocol or Postmark API.\n\n### Send by Postmark API \n\nTo send email with Postmark, you need to choose type of sending, api token options.\n \n``` ruby\napi_token = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'\n\nemail_sender = MailHandler.sender(type) do |dispatcher|\n    dispatcher.api_token = api_token\nend\n```\n\n* `:type` - type can be `:postmark_api` or `:postmark_batch_api`\n* `:api_token` - api token of one of your Postmark sending servers \n  \n### Sending email by SMTP\n\nTo send email with SMTP you need to configure standard SMTP settings.\nWe recommend to keep credentials for your SMTP settings safe, and read them from config file or environment variables.\nDo NOT keep credentials in your repositories. \n\n``` ruby\n\naddress = 'imap.example.com'\ndomain = 'example.com'\nport = 587\nusername = 'john'\npassword = 'xxxxxxxxxxxxxx'\nuse_ssl = true\n\nemail_sender = MailHandler.sender(:smtp) do |dispatcher|\n    dispatcher.address = address\n    dispatcher.port = port\n    dispatcher.domain = domain\n    dispatcher.username = username\n    dispatcher.password = password\n    dispatcher.use_ssl = use_ssl\nend\n```\n \n### Sending email\n \nOnce you have setup your email sender, all you need to do is to send an email:\n\n``` ruby\nemail_sender.send_email(email)\n```\n\nEmail you plan to send has to be an email created with Mail gem. \nIn order to send emails by Postmark batch, you will need to provide an Array of emails.\n\n## Sending results\n \nOnce email sending is finished, you can check sending result by looking at: `email_receiver.sending` object \n\n* `:started_at` - time when sending was initiated\n* `:finished_at` - time when sending was finished\n* `:duration` - time how long the sending took \n* `:response` - response from sending\n* `:email` - email sent\n \n### License\n\nMailHandler Library is licensed under the [MIT](http://www.opensource.org/licenses/mit-license.php \"Read more about the MIT license form\") license. Refere to the [LICENSE](https://github.com/ActiveCampaign/mailhandler/blob/master/LICENSE) file for more information. \n\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FActiveCampaign%2Fmailhandler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FActiveCampaign%2Fmailhandler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FActiveCampaign%2Fmailhandler/lists"}