Skip to content

Commit 2156350

Browse files
mludvigmludvig
committed
Added README.md
1 parent 1883f38 commit 2156350

4 files changed

Lines changed: 233 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
smtp-cli — command line SMTP client
2+
===================================
3+
4+
`smtp-cli` is a powerful **SMTP command line client** with a support for advanced features, such as **STARTTLS**, **SMTP-AUTH**, or **IPv6** and with a scriptable _message composition_ capabilities supporting anything from simple _plain-text_ messages right up to building _complex HTML emails_ with alternative plain-text part, attachments and inline images. The MIME-Type of the attachments can either be guessed automatically or alternatively set on the command line, separately for each attachment if required.
5+
6+
It's also a convenient tool for _testing_ and _debugging_ SMTP servers setups. Even the hardcore mail admins used to typing the SMTP protocol over telnet need a specialised tool when it comes to verifying encryption settings of their TLS enabled server with a subsequent user authentication. Such things are pretty hard to type into a telnet session by hand :-)
7+
8+
The name `smtp-cli` stands for:
9+
10+
1. **smtp-cli**ent
11+
2. **S**mtp-command **L**ine **I**nterface
12+
13+
Use `smtp-cli` if you want to:
14+
15+
1. check mail server capabilities
16+
2. test the server setup
17+
3. create and send complex emails from scripts or cron-jobs
18+
19+
The `smtp-cli` usage is intuitive, everything is scriptable and can run in a completely non-interactive mode from various scripts or cron jobs. It is also ideal for shipping log files from remote machines, running periodical mail delivery test loops, etc. Also if you ever needed to send a complex email with attachments from a command line, this script is all you need.
20+
21+
## Installation
22+
23+
Download the latest release from [smtp-cli on GitHub](https://github.com/mludvig/smtp-cli/releases) and make it executable:
24+
25+
```sh
26+
~ $ wget -o smtp-cli https://github.com/mludvig/smtp-cli/releases/{LATEST_RELEASE}
27+
~ $ chmod +x smtp-cli
28+
```
29+
30+
### Optional dependencies
31+
32+
Some features of smtp-cli are optional and available only when the appropriate perl modules are installed:
33+
34+
* RedHat Enterprise (RHEL), Fedora, Oracle Linux and CentOS users may want to install the following packages:
35+
36+
```sh
37+
$ sudo yum install perl-IO-Socket-SSL perl-Digest-HMAC perl-TermReadKey \
38+
perl-MIME-Lite perl-File-LibMagic perl-IO-Socket-INET6
39+
```
40+
41+
If `yum` can't find them all try to enable [EPEL repository](http://fedoraproject.org/wiki/EPEL).
42+
43+
* openSUSE and SUSE Enterprise (SLES) users should install these packages:
44+
45+
```sh
46+
$ sudo zypper install perl-IO-Socket-SSL perl-Digest-HMAC perl-TermReadKey \
47+
perl-MIME-Lite perl-File-LibMagic perl-IO-Socket-INET6
48+
```
49+
50+
* Users of Debian, Ubuntu and derivates should install these packages:
51+
52+
```sh
53+
$ sudo apt install libio-socket-ssl-perl libdigest-hmac-perl libterm-readkey-perl \
54+
libmime-lite-perl libfile-libmagic-perl libio-socket-inet6-perl
55+
```
56+
57+
Users of other Linux distributions will have to find the appropriate packages by themselves, or install the modules directly from [CPAN](http://cpan.perl.org/).
58+
59+
## Donate please :)
60+
61+
Please consider donating, even if it's just enough for a coffee.
62+
63+
[![Donate with PayPal](examples/PayPal-Donate-Button-PNG-Image.png)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=R8BYGL3B24QNE)
64+
65+
66+
67+
## Usage examples
68+
69+
These examples are for _testing_ and _verifying_ mail servers configurations:
70+
71+
### Example 1 - Test your localhost
72+
73+
The simplest example - it will not actually send anything. Only connect to a server, do some SMTP chatting and disconnect.
74+
75+
```
76+
$ ./smtp-cli --verbose --server localhost
77+
[220] 'localhost ESMTP Postfix'
78+
> EHLO localhost
79+
[250] 'localhost'
80+
[250] 'PIPELINING'
81+
[250] 'SIZE 20480000'
82+
[250] 'ETRN'
83+
[250] '8BITMIME'
84+
> QUIT
85+
[221] 'Bye'
86+
```
87+
88+
### Example 2 - Send an e-mail through a host which requires encryption and authentication
89+
90+
Things are getting more interesting. We will use `--server smtp.example.com:587` to connect to port 587
91+
that is usually used by email clients (port 25 is usually for server-to-server communication). Port 587
92+
also _usually_ requires authentication.
93+
94+
For that we'll supply `--user test` and optional `--password ...` to supply the credentials.
95+
If the password is not supplied we will be asked interactively.
96+
97+
To actually send something we will also supply `--from` and `--to` parameters and also `--data message.txt`.
98+
99+
Note tat this `message.txt` must contain both the _headers_ and the _message body_. If you don't want to
100+
bother with creating the message headers yourself use `--body` instead, see the next example for details.
101+
102+
```
103+
$ ./smtp-cli --verbose --host smtp.example.com:587 --enable-auth --user test \
104+
--from test@example.com --to user@another.example.org --data message.txt
105+
106+
[220] 'smtp.example.com ESMTP Postfix'
107+
> EHLO localhost
108+
[250] 'smtp.example.com'
109+
[250] 'PIPELINING'
110+
[250] 'SIZE 10240000'
111+
[250] 'VRFY'
112+
[250] 'ETRN'
113+
[250] 'STARTTLS'
114+
[250] 'XVERP'
115+
[250] '8BITMIME'
116+
Starting TLS...
117+
> STARTTLS
118+
[220] 'Ready to start TLS'
119+
Using cipher: EDH-RSA-DES-CBC3-SHA
120+
Subject Name: /C=XX/CN=smtp.example.com/Email=info@example.com
121+
Issuer Name: /C=XX/CN=Example.COM Root CA/Email=ca@example.com
122+
> EHLO localhost
123+
[250] 'smtp.example.com'
124+
[250] 'PIPELINING'
125+
[250] 'SIZE 10240000'
126+
[250] 'VRFY'
127+
[250] 'ETRN'
128+
[250] 'AUTH PLAIN LOGIN DIGEST-MD5 CRAM-MD5'
129+
[250] 'AUTH=PLAIN LOGIN DIGEST-MD5 CRAM-MD5'
130+
[250] 'XVERP'
131+
[250] '8BITMIME'
132+
AUTH method (PLAIN LOGIN DIGEST-MD5 CRAM-MD5): using CRAM-MD5
133+
> AUTH CRAM-MD5
134+
[334] 'PDE0OTQyOTcxOC4yNjAwOTYwQHNlcnZlci5kb21haW4udG9wPg=='
135+
> dGVzdCBmOTUyY2RkM2VlODBiMzk1YjYxNDI4NjBlYzg2Y2ExZnJvb3Q=
136+
[235] 'Authentication successful'
137+
Authentication of test@localhost succeeded
138+
> MAIL FROM: <test@example.com>
139+
[250] 'Ok'
140+
> RCPT TO: <user@another.example.org>
141+
[250] 'Ok'
142+
> DATA
143+
[354] 'End data with <CR><LF>.<CR><LF>'
144+
[250] 'Ok: queued as C5C3A299D7'
145+
> QUIT
146+
[221] 'Bye'
147+
```
148+
149+
### Example 3 - Compose a plain text email with attachments
150+
For composing emails you will need an optional `MIME::Lite` perl module. See the _Optional dependencies_ section above for details.
151+
152+
```
153+
$ ./smtp-cli [--server / --auth / --verbose flags] \
154+
--from test@domain.com --to user@another.domain.org \
155+
--subject "Simple test with attachments" \
156+
--body-plain "Log files are attached." \
157+
--attach /var/log/some.log@text/plain \
158+
--attach /var/log/other.log
159+
```
160+
161+
This example composes a standard plain text email with two attachments. The interesting part is the syntax used for enforcing _MIME-Type_ of the first attachment.
162+
163+
The syntax `some.log@text/plain` will make `some.log` attached as **text/plain** part, while the _MIME-Type_ of `other.log` will be guessed by the script and eventually default to **application/octet-stream**.
164+
165+
### Example 4 - Attachment as an email body
166+
```
167+
$ ./smtp-cli [--server / --auth / --verbose flags] \
168+
--from test@domain.com --to user@another.domain.org \
169+
--subject "Image as a mail body" \
170+
--attach /path/to/tux.png
171+
```
172+
173+
If there is only one text or image file to be sent, the file itself could be the message body. At the same time it will be accessible as an attachment with a file name for easy saving. Best to show a screenshot I guess...
174+
175+
![Attachment as an email body](examples/screenshot-img-body.png)
176+
177+
There is no _Text_ or _HTML_ body part and the email is not _multipart/mixed_. All that is in the email is Tux the Penguin image. You can immediately see it in your mailer but also can easily save it with its provided name tux.png. The same way it works with text files (or files forced to be text/plain, to be precise).
178+
179+
### Example 5 - Compose a multipart/alternative email with both HTML and Plain text part and inline images
180+
181+
Sending HTML emails is popular, especially among non-technical people. They like to change font colours, backgrounds, embed images and apply all sorts of other useless effects to their one short line of text. Indeed, me and you are more than happy with plain text and we both know that some mail readers can't even display colours and graphics at all (our office manager wouldn't believe!). Therefore it is a good practice for HTML messages to use **multipart/alternative** MIME format with _both_ HTML and TEXT parts. In this example we're going to go wild and even embed an inlined image or two into the HTML part.
182+
183+
First of all prepare the message body. Or bodies, actually. The HTML one is `body.html`:
184+
185+
```html
186+
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
187+
<html>
188+
<head></head>
189+
<body bgcolor="#ffffff" text="#000000">
190+
<div align="center">
191+
Here comes embedded <font color="#006600"><b>Mr Tux</b></font><br>
192+
<img src="cid:tux.png"><br>
193+
<i>Nice, isn't it?</i><br>
194+
<img src="cid:smiley.png"><br>
195+
</div>
196+
</body>
197+
</html>
198+
```
199+
200+
Note the `<img>` tags with `cid:filename.xyz` source — that's the way to refer _inlined attachments_ from inside the message. We will obviously have to inline-attach `tux.png` and `smiley.png` to the message to make it work.
201+
202+
The second body file is a _plain text_ representation of the above, call it `body.txt`:
203+
204+
```
205+
Here comes embedded Mr Tux
206+
... actually it doesn't ...
207+
Not in a text-only mail reader.
208+
Sorry
209+
```
210+
211+
That's it. Here comes the magic command line that puts it all together:
212+
213+
```
214+
$ ./smtp-cli --from test@domain.com --to user@another.domain.org \
215+
--subject "HTML with embedded image" \
216+
--body-html body.html --body-plain body.txt \
217+
--attach-inline tux.png --attach-inline smiley.png
218+
```
219+
220+
And this is what we get:
221+
222+
![Multipart HTML email with embedded image](examples/screenshot-img-inline.png)
223+
224+
## Donate please :)
225+
226+
Please consider donating, even if it's just enough for a coffee.
227+
228+
[![Donate with PayPal](examples/PayPal-Donate-Button-PNG-Image.png)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=R8BYGL3B24QNE)
229+
230+
231+
## Author
232+
233+
**Michael Ludvig** - get in touch through the [Issues](https://github.com/mludvig/smtp-cli/issues) section above.

‎examples/PayPal-Donate-Button-PNG-Image.png‎

38.1 KB
Loading

‎examples/screenshot-img-body.png‎

24.1 KB
Loading

‎examples/screenshot-img-inline.png‎

27.9 KB
Loading

0 commit comments

Comments
 (0)