{"id":20541187,"url":"https://github.com/netways/check_email","last_synced_at":"2025-05-09T13:31:25.223Z","repository":{"id":39861321,"uuid":"252133890","full_name":"NETWAYS/check_email","owner":"NETWAYS","description":"PoC for an Icinga plugin to check email delivery","archived":true,"fork":false,"pushed_at":"2023-05-16T09:10:28.000Z","size":47,"stargazers_count":3,"open_issues_count":0,"forks_count":4,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-03-21T14:18:04.282Z","etag":null,"topics":["email","icinga","monitoring","plugin"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NETWAYS.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":"2020-04-01T09:45:48.000Z","updated_at":"2024-05-13T09:26:03.000Z","dependencies_parsed_at":"2024-11-16T01:31:53.993Z","dependency_job_id":null,"html_url":"https://github.com/NETWAYS/check_email","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NETWAYS%2Fcheck_email","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NETWAYS%2Fcheck_email/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NETWAYS%2Fcheck_email/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NETWAYS%2Fcheck_email/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NETWAYS","download_url":"https://codeload.github.com/NETWAYS/check_email/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253258213,"owners_count":21879614,"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","icinga","monitoring","plugin"],"created_at":"2024-11-16T01:20:03.691Z","updated_at":"2025-05-09T13:31:24.972Z","avatar_url":"https://github.com/NETWAYS.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"**Warning:** This is an experimental Proof of Concept. Use with caution. You can delete your mails!\n\n# check_email\n\n#### Table of Contents\n\n1. [About](#about)\n2. [License](#license)\n3. [Usage](#usage)\n4. [Configuration](#configuration)\n5. [Thanks](#thanks)\n6. [Contributing](#contributing)\n\n## About\n\n*check_email* is a plugin to monitor email transmissions. It sends an email via SMTP to a\ngiven email-address and evaluates the email receipt via IMAP. Furthermore *check_email* can\nhandle echo replies. An echo reply or in other name *echo-mail* will be sent from a mail\nserver, which received an email and responds to it. The last feature which *check_email* offers,\nis a cleanup option. This allows to delete mails, which were sent by *check_email* or the *echo reply*.\n\n## License\n\nThis plugin is licensed under the terms of the GNU General Public License Version 2, you will\nfind a copy of this license in the LICENSE file included in the source package.\n\n## Usage\n\n### Send an email and check for its delivery\n\nIn order to send an email to a given IMAP server and check for its delivery, you have to set the\nrequired arguments *(see the example below)*. The plugin sends an email with an unique (hash) subject\nand *X-Custom-Tag* via SMTP to the specified email-address. Afterwards the plugin connects via IMAP\nto the given mail account and searches in the given mailbox for the email sent before. Dependent on\nthe thresholds, the plugin searches through the mailbox until the critical threshold is exceeded.\u003cbr\u003e\n\n**Required arguments:**\u003cbr\u003e\n      `--imap-host=[IMAP_HOST]`\u003cbr\u003e\n      `--imap-port=[IMAP_PORT]`\u003cbr\u003e\n      `--imap-user=[IMAP_USERNAME]`\u003cbr\u003e\n      `--imap-password=[IMAP_PASSWORD]`\u003cbr\u003e\n      `--smtp-host=[SMTP_HOST]`\u003cbr\u003e\n      `--smtp-port=[SMTP_PORT]`\u003cbr\u003e\n      `--smtp-user=[SMTP_USERNAME]`\u003cbr\u003e\n      `--smtp-password=[SMTP_PASSWORD]`\u003cbr\u003e\n      `--sender=[SENDER_ADDRESS]`\u003cbr\u003e\n      `--receiver=[RECEIVER_ADDRESS]`\u003cbr\u003e\n\n**If not otherwise specified, the default values will be applied:**\u003cbr\u003e\n      `--imap-port=993`\u003cbr\u003e\n      `--imap-mailbox='INBOX'`\u003cbr\u003e\n      `--smtp-port=465`\u003cbr\u003e\n      `--critical=500`\u003cbr\u003e\n      `--warning=300`\n\n### Check for echo replies\n\nIf the argument *--echo-reply* is set, the plugin assumes that an *echo-mail* will be send automatically\nfrom a mail server, to inform the sender of the previous sent email that the email has been\ndelivered. Therefore, the plugin searches for this specified *echo-mail* in the mailbox of the\nsender account via IMAP. Usually the *echo-mail* subject contains the same subject as the previous\nsent email e.g.: “RE: Subject”\n\u003eNOTE: This *echo function* has to be configured on the mail server.\n\n**Required arguments:**\u003cbr\u003e\n      `--echo-reply`\u003cbr\u003e\n\n**If not otherwise specified, the default values will be applied:**\u003cbr\u003e\n      `--imap-sender-host=[--smtp-host]`\u003cbr\u003e\n      `--imap-sender-port=993`\u003cbr\u003e\n      `--imap-sender-mailbox='INBOX'`\u003cbr\u003e\n      `--imap-sender-user=[--smtp-user]`\u003cbr\u003e\n      `--imap-sender-password=[--smtp-password]`\u003cbr\u003e\n      `--critical-reply=500`\u003cbr\u003e\n      `--warning-reply=300`\n\n### Cleanup\n\nIn order to avoid a full mailbox of *echo-mails* and *check-mails*, there is an argument *--cleanup*\nto delete *echo-mails* and *check-mails*.\n\u003eUse this option with caution, it could delete involuntary emails if the wrong *--imap-mailbox*,\n\u003e*--imap-sender-mailbox* or *--reply-name* is specified!\n\n**Required arguments:**\u003cbr\u003e\n      `--cleanup`\u003cbr\u003e\n      `--reply-name=[REPLY_NAME]`\u003cbr\u003e\n\n**If not otherwise specified, the default values will be applied:**\u003cbr\u003e\n      `--cleanup-time=3600`\n\n### Optional: environment variables\n\nCheck_email can gather these following environment variables from the system:\n\n\texport IMAP_USERNAME='username'\n\texport IMAP_PASSWORD='password'\n\texport SMTP_USERNAME='username'\n\texport SMTP_PASSWORD='password'\n\texport IMAP_SENDER_USERNAME='username'\n\texport IMAP_SENDER_PASSWORD='password'\n\n\u003eNOTE: It's currently not implemented to define more than one of each *SMTP*, *IMAP* and *IMAP_SENDER*\n\n## Example - Send an email and check for its delivery (without cleanup).\n\n\t./check_mail.py \\\n\t\t\t--smtp-host='mail.example.com' \\\n\t\t\t--smtp-port=587 \\\n\t\t\t--smtp-user='DOMAIN\\User' \\\n\t\t\t--smtp-password='***' \\\n\t\t\t--sender='sender@example.com' \\\n\t\t\t--imap-host='imap.example.com' \\\n\t\t\t--imap-port=993 \\\n\t\t\t--imap-user='receiver@example.de' \\\n\t\t\t--imap-password='***' \\\n\t\t\t--receiver='receiver@example.de' \\\n\t\t\t--imap-mailbox='Monitoring' \\\n\t\t\t--warning=300 \\\n\t\t\t--critical=500 \\\n            (optional) --subject='exampleSubject'\n\n\u003e1. The plugin connects to *mail\u003cspan\u003e.example.com*, creates an unique hash subject and sends an email\n\u003eto *receiver\u003cspan\u003e@example.com*\n\u003e2. The plugin connects to *imap\u003cspan\u003e.example.com*, searches trough the mailbox *Monitoring*. If '--subject' is set,\n\u003e the email will be checked and instantly deleted.\n\u003e3. If the email cannot be found within 300 seconds, the return state will be WARNING\n\u003e4. After 500 seconds, the plugin will exit and return a CRITICAL\n\n### Output - Send an email and check for its delivery (without cleanup)\n\n\tOK - check_email: imap.example.com - Email received in 3s | 'receive'=3\n\n \u003eThe email was found, and the plugin returns OK. Additionally, the duration how long this action took\n \u003ewill be served as *perfdata*.\n\n## Example - Check for echo replies (with cleanup)\n\n\t./check_mail.py \\\n\t\t\t--smtp-host='mail.example.com' \\\n\t\t\t--smtp-port=587 \\\n\t\t\t--smtp-user='DOMAIN\\User' \\\n\t\t\t--smtp-password='***' \\\n\t\t\t--sender='sender@example.com' \\\n\t\t\t--imap-host='imap.example.com' \\\n\t\t\t--imap-port=993 \\\n\t\t\t--imap-user='DOMAIN\\User' \\\n\t\t\t--imap-password='***'\\\n\t\t\t--receiver='receiver@example.com' \\\n\t\t\t--imap-mailbox='Monitoring' \\\n\t\t\t--warning=300 \\\n\t\t\t--critical=500 \\\n\t\t\t--echo-reply \\\n\t\t\t--imap-sender-host='imap.sender.example.com' \\\n\t\t\t--imap-sender-port=993 \\\n\t\t\t--imap-sender-user='DOMAIN\\User' \\\n\t\t\t--imap-sender-password='***' \\\n\t\t\t--imap-sender-mailbox='Monitoring' \\\n\t\t\t--reply-name='Echo Notify' \\\n\t\t\t--warning-reply=300 \\\n\t\t\t--critical-reply=500 \\\n\t\t\t--cleanup \\\n\t\t\t--cleanup-time=300\n\n\u003e1. The plugin connects to *mail\u003cspan\u003e.example.com*, creates an unique hash subject and sends an email\n\u003eto *receiver\u003cspan\u003e@example.com*.\n\u003e2. The plugin connects to *imap\u003cspan\u003e.example.com*, searches trough the mailbox *Monitoring*. Additionally,\n\u003eemails with the *X-Custom-Tag* and if they are older then 300 seconds, will be deleted.\n\u003e3. If the email cannot be found within 300 seconds, the state will be WARNING\n\u003e4. After 500 seconds the plugin will exit and return a CRITICAL\n\u003e5. If the email was found, the plugin connects to *imap\u003cspan\u003e.sender.example.com*\n\u003e6. The plugin selects the mailbox *Monitoring* and searches for the assumend *echo-mail*, which should\n\u003econtain **Echo Notify** in the subject. Additionally, old *echo-mails*  will be deleted (see 2.)\n\u003e7. If the *echo-mail* cannot be found within 300 seconds, the return state will be WARNING\n\u003e8. After 500 seconds, the plugin will exit and return a CRITICAL\n\n### Output - Email loop example with cleanup\n\n\tOK - check_email: Email loop took 7s | 'receive'=3 'reply'=4 'loop'=7\n\n\u003eThe *sent-mail* and *echo-mail* was found and the plugin returns OK. Additionally, the duration\n\u003ehow long each action took will be served as *perfdata*.\u003cbr\u003e\n\n\u003eNOTE: The output will be always the *highest* state, e.g.: *receive* is WARNING and *reply* is,\n\u003ethe plugin output will be WARNING.\n\n## Configuration\n\n### Icinga \n\n**IMPORTANT**\n`check_timeout` must be greater than the `critical threshold` otherwise the *default timeout* of a\nplugin could be exceeded and Icinga kills its process. As a result, the plugin can never reach the\n*critical* state. Moreover `check_interval` has also to be lower than the `check_timeout`. Due to\nthe fact, that the plugin *waits* for an email or rather an event, the execution time could be, in\nthe worst case, higher than the `check_interval`. In such circumstances Icinga triggers *check_email*\nagain, even if the plugin did not finish correctly.\n\n\u003eSee *check_email.conf* for an example configuration\n\n### Mail server\nIt is recommended to configure rules to manage emails from this plugin. By using a rule, any received\nemail message that match conditions specified in the rule can be automatically forwarded or redirected\nto another mailbox (**of the same account!**). This is very useful, since the plugin searches through\na given mailbox. It could be a negative impact if the specified mailbox is filled up with other mails,\nwhich are also be evaluated.\n\n## Thanks\n\n- Michael Friedrich\n- Markus Frosch\n- Markus Waldmüller\n\n## Contributing\n\nThere are many ways to contribute to *check_email* -- whether it be sending patches, testing, reporting bugs,\nor reviewing and updating the documentation. Every contribution is appreciated!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetways%2Fcheck_email","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetways%2Fcheck_email","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetways%2Fcheck_email/lists"}