Linux Command Line Email HOWTO
A guide to using ssmtp and mime-construct .
Sending email from the command line (terminal/console) used to be easy, and was abused by spammers. Now it's more secure, and less easy, but it can be made easier by installing the right tools and configuring them correctly. You can also send HTML formatted messages and binary attachments directly from the command line.
This guide assumes you do not, and do not want to, have an email server installed locally; however the tips for MIME attachments are perfectly valid for local email servers.
Prerequisites
You will need a username and password for a secure outbound SMTP server that uses TLS. Almost certainly you will need your own domain, and configure that for your chosen SMTP provider, usually with SPF and DKIM DNS records. I used MailerSend's free "hobby" subscription, which allows for 1 domain and up to 3000 emails per month. Another good option is Google Workspace. If you don't have nor want your own domain, there is a guide to using ssmtp with a basic gmail account.
In the following examples, it is assumed that your email address, the one you are sending from - or at least, the one you want on the From: or Reply-To: headers - is: andrew@example.com
ssmtp
ssmtp is a command-line alternative to the ever-popular sendmail command, that supports TLS. It acts as its own outbound mail transfer agent (MTA); you do not need a separate email server. You can install it on Debian-based systems, such as Ubuntu, with:
sudo apt update && sudo apt install ssmtp
Once installed, configure it by editing /etc/ssmtp/ssmtp.conf :
# Config file for sSMTP sendmail
#
# The place where the mail goes. The actual machine name is required; no
# MX records are consulted. Commonly mailhosts are named mail.domain.com
mailhub=smtp.mailersend.net:587
#UseTLS=YES
UseSTARTTLS=YES
AuthUser=MAILERSEND_SMTP_USERNAME@example.com
AuthPass=MAILERSEND_SMTP_PASSWORD
# Where will the mail seem to come from?
# If a FROM address isn't provided,
# FROM: will be username@rewriteDomain
# If not set, uses hostname.
#rewriteDomain=
# The full hostname
hostname=example.com
# Are users allowed to set their own From: address?
# YES - Allow the user to specify their own From: address
# NO - Use the system generated From: address
FromLineOverride=YES
It's important to note that your outbound email provider might set restrictions on, or override, these values. For example, a modern mail server is unlikely to allow you to impersonate a domain you haven't proved you own. Correct DNS records for SPF and DKIM are beyond the scope of this tutorial; consult the documentation from your outbound email provider.
The last piece of configuration, is that the Linux user that will be sending email, needs to be a member of the "mail" group. For example, my username is: aoakley
sudo usermod -a -G mail aoakley
Once this is done, log out and log in again to make the group change happen. Then you should be able to send a plain-text email from the command line:
echo -e "From: andrew@example.com\nSubject: Test from ssmtp\n\nThis is the email body" | ssmtp test-email-address@gmail.com
Note how the header is separated from the body with two newlines.
An interesting gotcha is that most terminal shells use BASH/DASH, whereas crontab uses plain old SH. One notable difference is that SH tends to have echo configured to already include -e for escape characters. If you're using ssmtp in a crontab, try echo without the
mime-construct
The basic ssmtp command is fine for plain text email, but you might want to add an attachment, or send HTML-formatted messages.
mime-construct creates a MIME message and sends it using sendmail - i.e. ssmtp if you have that installed. It guesses the mime-type from the attachment file extension
Plain text message with a binary attachment
mime-construct --to test-email-address@gmail.com --header "From: Bobby Tables <andrew@example.com>" --header "Reply-To: andrew@example.com" --subject "Test attachment" --string "Please find your file attached." --file-attach "test.jpg"
The From: and Reply-To: headers are optional; if not supplied, they'll use whatever you configured for ssmtp or your TLS acount.
You can have multiple attachments; just repeat the --file-attach "filename.ext" parameter. Be aware that sooner or later, you will hit an attachment limit, either number of files, or size of an individual file, or total size of all files. 5MB is a pretty conservative guess but many systems allow up to 20MB. 64MB is not unknown but larger than that is rare.
HTML formatted body
Note that mime-construct automatically adds a plain-text body too, so it should be readable on terminal-based email clients as well as GUI/web ones. The parameter --file - (dash instead of a filename) indicates that it reads from piped output / stdin.
echo "<P>Here is some <B>bold</B> text" | mime-construct --to test-email-address@gmail.com --subject "HTML formatted text" --type text/html
You can force monospaced text with newlines by enclosing it in HTML <PRE> ... </PRE> tags. This is ideal for piped output. Some email clients might use monospace by default; "it depends".
HTML formatted text and attachment
echo "<P>Here is some <B>bold</B> text" | mime-construct --to test-email-address@gmail.com --subject "HTML formatted text" --file-attach "test.jpg" --type text/html
HTML message and embedding an image
...rather than attaching it. Note the prefix of cid: before the filename in the IMG tag.
echo "<P>Here's that photo:<P><IMG SRC='cid:test.jpg' WIDTH=400 HEIGHT=300>" | mime-construct --to test-email-address@gmail.com --subject "HTML with embedded image" --file-attach "test.jpg" --type text/html
The cid: method definitely works for Gmail and Outlook. It seems widely supported but it is not guaranteed to work with every email client. There is another method involving base64 encoding the image data, which is less well supported, but I couldn't get it to work - or at least, I couldn't get it to work with my Gmail test account. Another method is to host the image on a web server, and link as usual using <IMG SRC="https://whatever"> but that might be considered a "web bug" and blocked by default (the email client usually prompts the user to decide whether to download images).
Comments, errors and corrections to: andrew@aoakley.com
Public Domain - Andrew Oakley - 2025-03-12
