Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

smtp-cli — command line SMTP client

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.

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 :-)

The name smtp-cli stands for:

  1. smtp-client
  2. Smtp-command Line Interface

Use smtp-cli if you want to:

  1. check mail server capabilities
  2. test the server setup
  3. create and send complex emails from scripts or cron-jobs

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.


Download the latest release from smtp-cli on GitHub and make it executable:

~ $ wget -o smtp-cli{LATEST_RELEASE}
~ $ chmod +x smtp-cli

Optional dependencies

Some features of smtp-cli are optional and available only when the appropriate perl modules are installed:

  • RedHat Enterprise (RHEL), Fedora, Oracle Linux and CentOS users may want to install the following packages:

    $ sudo yum install  perl-IO-Socket-SSL  perl-Digest-HMAC  perl-TermReadKey  \
                          perl-MIME-Lite  perl-File-LibMagic  perl-IO-Socket-INET6

    If yum can't find them all try to enable EPEL repository.

  • openSUSE and SUSE Enterprise (SLES) users should install these packages:

    $ sudo zypper install  perl-IO-Socket-SSL  perl-Digest-HMAC  perl-TermReadKey  \
                             perl-MIME-Lite  perl-File-LibMagic  perl-IO-Socket-INET6
  • Users of Debian, Ubuntu and derivates should install these packages:

    $ sudo apt install  libio-socket-ssl-perl  libdigest-hmac-perl  libterm-readkey-perl \
                          libmime-lite-perl libfile-libmagic-perl libio-socket-inet6-perl

Users of other Linux distributions will have to find the appropriate packages by themselves, or install the modules directly from CPAN.

Donate please :)

Please consider donating, even if it's just enough for a coffee.

Donate with PayPal

Usage examples

These examples are for testing and verifying mail servers configurations:

Example 1 - Test your localhost

The simplest example - it will not actually send anything. Only connect to a server, do some SMTP chatting and disconnect.

$ ./smtp-cli --verbose --server localhost
[220] 'localhost ESMTP Postfix'
> EHLO localhost
[250] 'localhost'
[250] 'SIZE 20480000'
[250] 'ETRN'
[250] '8BITMIME'
[221] 'Bye'

Example 2 - Send an e-mail through a host which requires encryption and authentication

Things are getting more interesting. We will use --server to connect to port 587 that is usually used by email clients (port 25 is usually for server-to-server communication). Port 587 also usually requires authentication.

For that we'll supply --user test and optional --password ... to supply the credentials. If the password is not supplied we will be asked interactively.

To actually send something we will also supply --from and --to parameters and also --data message.txt.

Note tat this message.txt must contain both the headers and the message body. If you don't want to bother with creating the message headers yourself use --body instead, see the next example for details.

$ ./smtp-cli --verbose --host --enable-auth --user test \
--from --to --data message.txt

[220] ' ESMTP Postfix'
> EHLO localhost
[250] ''
[250] 'SIZE 10240000'
[250] 'VRFY'
[250] 'ETRN'
[250] 'STARTTLS'
[250] 'XVERP'
[250] '8BITMIME'
Starting TLS...
[220] 'Ready to start TLS'
Using cipher: EDH-RSA-DES-CBC3-SHA
Subject Name: /C=XX/
Issuer  Name: /C=XX/CN=Example.COM Root CA/
> EHLO localhost
[250] ''
[250] 'SIZE 10240000'
[250] 'VRFY'
[250] 'ETRN'
[250] 'XVERP'
[250] '8BITMIME'
[334] 'PDE0OTQyOTcxOC4yNjAwOTYwQHNlcnZlci5kb21haW4udG9wPg=='
> dGVzdCBmOTUyY2RkM2VlODBiMzk1YjYxNDI4NjBlYzg2Y2ExZnJvb3Q=
[235] 'Authentication successful'
Authentication of test@localhost succeeded
[250] 'Ok'
> RCPT TO: <>
[250] 'Ok'
[354] 'End data with <CR><LF>.<CR><LF>'
[250] 'Ok: queued as C5C3A299D7'
[221] 'Bye'

Example 3 - Compose a plain text email with attachments

For composing emails you will need an optional MIME::Lite perl module. See the Optional dependencies section above for details.

$ ./smtp-cli [--server / --auth / --verbose flags] \
             --from --to \
             --subject "Simple test with attachments" \
             --body-plain "Log files are attached." \
             --attach /var/log/some.log@text/plain \
             --attach /var/log/other.log

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.

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.

Example 4 - Attachment as an email body

$ ./smtp-cli [--server / --auth / --verbose flags] \
             --from --to \
             --subject "Image as a mail body" \
             --attach /path/to/tux.png

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...

Attachment as an email body

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).

Example 5 - Compose a multipart/alternative email with both HTML and Plain text part and inline images

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.

First of all prepare the message body. Or bodies, actually. The HTML one is body.html:

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<body bgcolor="#ffffff" text="#000000">
<div align="center">
Here comes embedded <font color="#006600"><b>Mr Tux</b></font><br>
<img src="cid:tux.png"><br>
<i>Nice, isn't it?</i><br>
<img src="cid:smiley.png"><br>

Note the <img> tags with 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.

The second body file is a plain text representation of the above, call it body.txt:

Here comes embedded Mr Tux
... actually it doesn't ... 
Not in a text-only mail reader.

That's it. Here comes the magic command line that puts it all together:

$ ./smtp-cli --from --to \
             --subject "HTML with embedded image" \
             --body-html body.html --body-plain body.txt \
             --attach-inline tux.png --attach-inline smiley.png

And this is what we get:

Multipart HTML email with embedded image

Donate please :)

Please consider donating, even if it's just enough for a coffee.

Donate with PayPal


Michael Ludvig - get in touch through the Issues section above.


The ultimate command line SMTP client






No packages published