==========================
|Mail Alert Simple Mailer|
==========================
Version: 1.08
Date: September, 2017
Author: MediLogic Adam Luszczewski
Contact: biuro@medilogic.pl
What is it?
-----------
Mail Alert Simple Mailer is a simple command-line utility designed for IT administrators for sending e-mail from Microsoft Windows OS. It can be executed from command line, Windows batch file or PowerShell scripts. My main reason for writing this software was to handle events generated by Dell OpenManage Server Administrator (OMSA), APC PowerChute and Windows Events to send hardware status and alerts like temperature alerts, UPS battery status, powerline status and RAID controller alerts from monitoring software. It can be used with any other software where you can configure external application to be executed when specific event occurs.
Mail Alert Simple Mailer supports SSL and STARTTLS protocols, so it is compatible with many free e-mail providers like GMail, Hotmail, etc. Unlike other simple command line tools it supports ISO-8859-1, ISO-8859-2 and UTF-8 code pages for national characters. In contrast to PowerShell scripts and similar command-line utilities Mail Alert encrypts SMTP password in configuration file.
Software features:
- sends e-mail from command-line to single or multiple recipients with mail subject and body defined in command-line parameters,
- e-mail recipient, subject, body text or body from file, attachment and e-mail importance (priority) can be defined as command-line parameter,
- mail server parameters like host name, username, password, port and protocol, as well as e-mail sender with name, e-mail recipient, CC, BCC, e-mail importance, e-mail text code page can be configured in INI configuration file to avoid long list of parameters when executing from command line,
- SMTP password is stored in configuration file in encrypted form using symmetric-key block cipher with 448 bits encryption key,
- supports plain text and HTML e-mail body which can be loaded from external file,
- supports SMTP-AUTH,
- supports SSL/TLS and STARTTLS,
- supports sending e-mail attachment. You can send as many files as you want in one attachment file using external compression tool like ZIP, 7-ZIP, RAR or similar solution,
- supports characters encoding in code page UTF-8, ISO-8859-1 and ISO-8859-2,
- local system date and time can be automatically added to e-mail body,
- supports Verbose Mode to view communication details with SMTP server. It is very useful for SMTP server diagnostics.
- supports all SMTP mail servers compliant with RFC Internet standards (including Gmail, etc.),
- generates Exit Codes (error levels) when operation was successfully completed or specific error occurred,
- tested on 32 bit and 64 bit Windows OS including Windows Server editions.
How to start?
-------------
Before first use make sure you have configured all required parameters in MAILALERT.INI configuration file.
Contact your mail server administrator for details such as: SMTP server, SMTP port number, whether your SMTP server supports SSL/TLS and on which port number.
When all required parameters are entered in configuration file try to send test message using the following command:
MailAlert -t
When configuration is correct, you should receive a test e-mail. In case of error it is recommended to set VerboseMode=yes in configuration file to diagnose the issue.
How to configure?
-----------------
Configuration parameters are stored in MAILALERT.INI file located in c:\MailAlert folder. Please make sure that you have write permission to MAILALERT.INI file.
All configuration parameters are located in one common [CONFIGURATION] section.
To=
Recipient e-mail address (To:). You can override this setting with command line -r parameter. Use comma or semicolon to separate e-mail addresses for multiple recipients. Required parameter.
From=
Sender e-mail address (From:).
Required parameter.
CC=
Carbon copy (Cc:) e-mail address(es). You can override this setting with command line -c parameter. Use comma or semicolon to separate e-mail addresses for multiple recipients.
Optional parameter.
BCC=
Blind carbon copy (Bcc:) e-mail address(es). You can override this setting with command line -u parameter. Use comma or semicolon to separate e-mail addresses for multiple recipients.
Optional parameter.
FullName=
Sender full name. If national characters are used, please make sure that correct code page is selected in Charset parameter.
Optional parameter.
ReplyTo=
Return e-mail address (ReplyTo:).
Optional parameter.
SMTPServer=
SMTP mail server address. It can be a domain name address or IP address.
Required parameter.
SMTPPort=
SMTP mail server port number. The IANA registered port number 25 for Simple Mail Transfer and port number 587 for Message Submission. Please contact you e-mail administrator for details.
Required parameter.
Username=
SMTP mail server username. Be aware, that some mail servers use your e-mail address as a username. Contact your mail server administrator for details.
Required parameter.
Password=
SMTP mail server password. Plain text Password value will be automatically converted to encrypted EncryptedPassword value after the first run (plain text password will be removed from configuration file).
Required parameter.
EncryptedPassword=
This parameter should never be edited manually. It contains encrypted SMTP mail server password entered in Password parameter. If you need to change your SMTP mail server password, enter a new value in Password parameter and run Mail Alert to convert it to EncryptedPassword. This operation requires write access to INI file.
Parameter created automatically. Dont edit it manually!
EnableAutoTLS=
This parameter defines whether mail server supports StartTLS encryption mode or not. If set to yes, then StartTLS mode will be used.
Allowed values are: yes or no.
Required parameter.
EnableSMTPS=
This parameter defines whether mail server supports SMTPS or not. If set to yes, then SSL/TLS mode is used from first contact to server, usually using non-standard TCP port. Originally, the IANA registered port number 465 for SMTPS. SMTPS was revoked when StartTLS had been specified, but is still used by many mail servers till now. When EnableAutoTLS is set to yes then you should set EnableSMTPS to no. Please contact you e-mail administrator for details.
Allowed values are: yes or no.
Required parameter.
Importance=
Set default e-mail importance level.
Allowed values are: High or Normal or Low.
Required parameter.
VerboseMode=
Set Verbose Mode to see SMTP commands results. This parameter is useful for mail server connection diagnostic.
Allowed values are: yes or no.
Optional parameter.
PlaintextOnly=
Choose e-mail body format. Set to yes to send e-mail body in plain text only (HTML tags will be ignored). Set to no if you need to send e-mail body in HTML format.
Allowed values are: yes or no.
Required parameter.
Charset=
Enter allowed code page character encoding. All e-mail parts like name, mail subject and mail body have to use code page chosen in this parameter.
Please make sure that MAILALERT.INI file is in UTF-8 format if Charset is set to UTF-8, otherwise use ASCII encoding (default).
Please do not use Windows batch for processing e-mails using Mail Alert Simple Mailer when Charset is set to UTF-8. Please use PowerShell scripts for better compatibility in such a case.
Allowed values are: ISO-8859-1, ISO-8859-2 or UTF-8.
Required parameter.
AlternativeSpaceEncoding=
According to RFC1521 SPACE character in the "Quoted-Printable" encoding may be represented as SPACE character. However, some mail readers do not support this encoding correctly. RFC1522 allows that SPACE character may be alternatively represented as "_" (underscore, ASCII 95.). If your mail reader incorrectly display mail Subject like "=?UTF-8?Q?" then set AlternativeSpaceEncoding parameter to yes.
Allowed values are: yes or no.
Required parameter.
Special notes for Gmail users
-----------------------------
Use 16-digit App password instead of Gmail password if your Gmail account has enabled 2-Step Verification (also known as two-factor authentication). Visit the following webpage to generate 16-digit App password:
https://security.google.com/settings/security/apppasswords
Syntax
------
Usage: MailAlert.exe <options>
<options>:
-h Display this help.
-t Send a test e-mail.
-r "admin@example.org" Set e-mail recipient address (To:) as a parameter.
-s "Subject" Set e-mail subject as a parameter.
-b "Body text" Set e-mail body as a parameter.
-c "admin2@example.org" Set e-mail Carbon Copy (Cc:) as a parameter.
-u "boss@example.org" Set e-mail Blind Carbon Copy (Bcc:) as a parameter.
-b "@File" Get e-mail body from a text File (HTML, TXT).
-i "High|Normal|Low" Set e-mail importance level as a parameter.
-a "File" Attach a File as an e-mail attachment.
-d Add local system date and time to message body.
Examples
--------
Send a test e-mail:
C:\> MailAlert -t
Send an e-mail using defined in command line parameters subject and priority:
C:\> MailAlert -s "Mail subject" -p "High"
Send an e-mail using defined in command line parameters recipient, subject and body (configuration file settings will be ignored). Add local date and time on the bottom of e-mail body:
C:\> MailAlert -r "admin@example.org" -s "Mail subject" -b "Mail body." -d
Send an e-mail using defined in command line parameters subject and body. Add local date and time on the bottom of e-mail body:
C:\> MailAlert -s "Mail subject" -b "Mail body." -d
Send an e-mail using defined in command line parameters subject and C:\index.html file as a mail body. Remember to set in configuration file parameter PlaintextOnly=no and choose correct Charset:
C:\> MailAlert -s "Mail subject" -b "@C:\index.html"
Send an e-mail using defined in command line parameters subject, body and C:\file.zip attachment:
C:\> MailAlert -s "Mail subject" -b "Mail body." -a "C:\file.zip"
Exit Codes
----------
List of Exit Codes (error levels) after Mail Alert Simple Mailer execution:
0 - no errors, your message has been sent successfully
1 - Configuration file not found!
2 - incorrect e-mail To: address!
3 - incorrect e-mail From: address!
4 - incorrect e-mail CC: address
5 - Incorrect e-mail BCC: address!
6 - Incorrect e-mail ReplyTo: address!
7 - SMTP Server address is empty!
8 - SMTP Server Port number is empty!
9 - SMTP Server Port number is incorrect!
10 - E-mail Username is empty!
11 - AlternativeSpaceEncoding is empty!
12 - SMTP Server Password is empty!
13 - E-mail importance ... is not supported according to RFC4021!
14 - Charset ... is not supported!
15 - Attachment file has not been found!
16 - file libeay32.dll has not been found!
17 - File ssleay32.dll has not been found!
18 - Check configuration file permissions: writing error!
19 - General configuration file error!
20 - Can not send your message!
100 - syntax error
RFC References
--------------
https://tools.ietf.org/html/rfc2476
https://tools.ietf.org/html/rfc6409
https://tools.ietf.org/html/rfc3207
https://tools.ietf.org/html/rfc1521
https://tools.ietf.org/html/rfc1522
