Skip to content

Notification notify-host-mail

Overview

Sends host notifications via email for Icinga/Nagios. Generates an HTML-formatted email with color-coded notification types and host states, including an embedded Icinga logo. Includes host display name, state, output, IP address, event time, perfdata, and an optional link to Icinga Web 2.

Important Notes:

  • Designed for use with the Linuxfabrik Icinga Director Basket. The basket wires every Icinga macro ($host.state$, $host.display_name$, $notification.author$, etc.) to the parameter names the plugin actually expects (--host-state, --host-displayname, --notification-author, ...). Icinga's stock ITL notification templates (mail-host-notification from icinga2-common) use different parameter names (--hoststate, --hostdisplayname, --longdatetime, ...) and will not work with this plugin. If you plug the plugin directly into the stock ITL template, argparse fails with "the following arguments are required: ..." because the names do not match. Import the basket into Icinga Director instead.
  • Use the --short parameter to create a short message without a subject, for example for sending to a SMS relay service.

Data Collection:

  • All notification data is passed via command-line parameters from the Icinga/Nagios notification system
  • Sends the email via SMTP (--mail-server, default: localhost, port 25)
  • Supports SMTP authentication via --mail-user and --mail-password

Fact Sheet

Fact Value
Notification Plugin Download https://github.com/Linuxfabrik/monitoring-plugins/tree/main/notification-plugins/notify-host-mail
Can be called without parameters No
Compiled for Windows No

Help

usage: notify-host-mail  [-h] [-V] --datetime DATETIME --host-displayname
                         HOST_DISPLAYNAME [--host-address HOST_ADDRESS]
                         [--host-output HOST_OUTPUT] --host-state HOST_STATE
                         [--hostname HOSTNAME]
                         [--icingaweb2-url ICINGAWEB2_URL]
                         [--mail-password MAIL_PASSWORD]
                         [--mail-port MAIL_PORT]
                         [--mail-recipient MAIL_RECIPIENT]
                         [--mail-sender MAIL_SENDER]
                         [--mail-server MAIL_SERVER]
                         [--mail-user MAIL_USER] [--notes NOTES]
                         [--notes-url NOTES_URL]
                         [--notification-author NOTIFICATION_AUTHOR]
                         [--notification-comment NOTIFICATION_COMMENT]
                         [--notification-type NOTIFICATION_TYPE]
                         [--perfdata PERFDATA] [--short]

Sends notifications for hosts using mail.

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  --datetime DATETIME   Set the message timestamp.
  --host-displayname HOST_DISPLAYNAME
                        Set the display name of the host.
  --host-address HOST_ADDRESS
                        Set the IPv4 address of the host.
  --host-output HOST_OUTPUT
                        Set the host output.
  --host-state HOST_STATE
                        Set the host state.
  --hostname HOSTNAME   Set the hostname.
  --icingaweb2-url ICINGAWEB2_URL
                        Set the Icinga Web 2 URL, for example
                        "https://example.com/icingaweb2".
  --mail-password MAIL_PASSWORD
                        Set the mail server login password.
  --mail-port MAIL_PORT
                        Set the mail server port. Default: 25.
  --mail-recipient MAIL_RECIPIENT
                        Set the mail recipient.
  --mail-sender MAIL_SENDER
                        Set the mail sender.
  --mail-server MAIL_SERVER
                        Set the mail server. Default: localhost.
  --mail-user MAIL_USER
                        Set the mail server login user.
  --notes NOTES         Set the notes.
  --notes-url NOTES_URL
                        Set the notes url.
  --notification-author NOTIFICATION_AUTHOR
                        Set the author of the comment.
  --notification-comment NOTIFICATION_COMMENT
                        Set the comment.
  --notification-type NOTIFICATION_TYPE
                        Set the type of notification like "PROBLEM" or
                        "RECOVERY".
  --perfdata PERFDATA   Set the perfdata.
  --short               Send a short message. This can be useful when using a
                        SMS relay, for example.

Usage Examples

./notify-host-mail \
    --datetime="2026-04-09 10:30:00" \
    --host-displayname="webserver01" \
    --host-state=DOWN \
    --hostname=webserver01.example.com \
    --host-address=192.168.1.10 \
    --notification-type=PROBLEM \
    --mail-recipient=admin@example.com \
    --mail-sender=icinga@example.com

Short message (e.g. for SMS relay):

./notify-host-mail \
    --short \
    --datetime="2026-04-09 10:30:00" \
    --host-displayname="webserver01" \
    --host-state=DOWN \
    --mail-recipient=sms-relay@example.com \
    --mail-sender=icinga@example.com

Credits, License