Sometimes you’re running a server to provide a specific service (Webserver, DNS, DHCP, git server, etc.) and you need it to send you status updates via email but do NOT need the overhead and complexity of having it run a mailserver or complicated MTA. You just need a SIMPLE, quick and easy way to have your server send a message over SMTP via a public mailserver… let’s look at msmtp.

What is msmtp?

msmtp is an SMTP client that submits mail to a server for further processing and delivery.  That’s it.  Nothing more, nothing less.  That’s why it’s lightweight, fast and simple to get going.  It allows attachments and fully supports encryption.  It’s exactly what you need to just have your little server send out status updates or even a cry for help!

The setup

This is basically how it works:

  • Email is generated by an app/user
  • msmtp is called to submit email to a mail server using provided credentials
  • the external mail server processes the message and completes the task of delivering it to the intended recipient

Install msmtp


Before getting started, I strongly suggest uninstalling sendmail and other MTAs such as postfix that might already be installed by default on your system but are not being used.  This will avoid conflicts and confusion.  If you’re already using postfix/sendmail, then there is no need for the following setup at all.

Ok, let’s get this program installed and then we’ll take a look at the configuration.  On Debian/Ubuntu systems, you can use apt to do all the work for you.

apt-get install msmtp msmtp-mta

That’s it.  msmtp is a program, not a service, so there is no systemd file or anything you need to worry about.  If ca-certificates was not auto-selected for installation along with msmtp, you should probably install that or verify it’s already installed since you’ll 99% be using that package. If it’s already installed, running the following command won’t hurt anything, it’ll just tell you it’s already up-to-date and ready to go.

apt-get install ca-certificates


Unlike other full MTA solutions, the setup for msmtp is very simple and only a few lines long (for our purposes).  Here’s the entire (commented) file… we’ll go through it after you bask in its brevity:

### mSMTP configuration

## Set defaults for all accounts
auth on
tls on
tls_trust_file /etc/ssl/certs/ca-certificates.crt
logfile /var/log/msmtp.log

## Account:
port 587
from "ServerName VM" <[email protected]>
user [email protected]
password [email protected]$$w0rd_

## Set default account
account default:
aliases /etc/msmtp_aliases

Configuration breakdown: How it works

I’ve shown you a commented breakdown and the parameters themselves are pretty much plain-English, but I’ll go through them one at a time since I find that virtually all open-source stuff lacks decent documentation written for humans.  <rant>Why can’t software authors write documentation that normal people can follow without having to google nine-thousand other things to understand what’s going on??? </rant>

The ‘defaults’ section

This sets parameters for the program in general.

## Set defaults for all accounts
auth on
tls on
tls_trust_file /etc/ssl/certs/ca-certificates.crt
logfile /var/log/msmtp.log

This tells msmtp that this section will contain program default settings.  It is a ‘section header’ and does not have any options or anything for you to monkey-around with.
This specifies whether or not SMTP authentication is required.  This is pretty much always required to be ‘on’ since you need at least a username/password combination to access most any mail server.  Setting this to ‘on’ tells msmtp to automatically detect and use the correct and most secure authentication method your target server supports.
This turns on TLS mode.  This is also referred to as SSL by some mail providers.  If your mail server supports encrypted connections (it should!) and uses port 587, then you’ll want to use this setting.  If your mail provider uses port 465 it is probably using SMTP/S or SMTP tunnelling.  In these cases, TLS is implied from the start so add ‘tls_starttls off’ after this line.
This specifies the location of public certificates to reference and enforces strict certificate checks.  If your mail server is using a certificate from a well known public certificate authority (including Let’s Encrypt) then its public certificate is included in the list maintained in the ca-certificates package in the Debian/Ubuntu repos.  You very very very likely do NOT need to change this line.  Two notes:

  1. If your mail server is using a private CA or using a self-signed cert, you’ll have to update this line to point to a PEM-encoded copy of the CA’s PUBLIC root certificate so msmtp can verify against it.
  2. If you don’t have a file at /etc/ssl/certs/ca-certificates, then install ca-certificates (apt-get install ca-certificates on Debian/Ubuntu).

Log files are important to keep track of what is using msmtp to send email and for troubleshooting purposes.  This specifies where you want that log file stored.  I have specified the default location on Debian systems with a meaningful filename.  You may choose any location and name you like, provided the program/user invoking msmtp has write permissions to that location.

The ‘accounts’ section

Here you can list the various accounts you’d like msmtp to use.  In this example, I’m only using one but you can create a few other sections if you need/want to sent mail via several accounts.

## Account:
account (13)
host (14)
port 587 (15)
from “ServerName VM” <[email protected]> (16)
user [email protected] (17)
password [email protected]$$w0rd_ (18)

Here we are specifying a name for the account profile.  I like naming it after my mailserver so I remember what’s going on.  So you could name it ‘’ or ‘’ or ‘’.  On the other hand, you could name it something like ‘MyMailServer’ or ‘MainProfile’… whatever has meaning to you, with no spaces.
This is the actual address of the mail server you want to use.  For Gmail, for example, it’s
The port on which your server accepts mail for relaying.  Traditionally, this is port 25.  Nearly ALL modern systems use port 587 for TLS encrypted connections.  As noted in the previous section, your server may use port 465 if it expects SSL connections/ tunnelled connections (sometimes called SMTP/S).
Here you can get creative.  In the quotes, you can write a name as you want it to appear.  So for a web server VM that you are running, you might want it to show up as “Webserver VM” in the ‘from:’ field of your email program.  You can really write anything here within reason.  Remember that most email clients expect something like “Firstname Lastname” here so something like “Server monitor on web server” might not show up properly in mail programs.  The part in <angle brackets> is the actual email address.  This must be a proper email address that is authorized to relay through the server in question.  In other words, a legitimate email account on the server to which you are connecting — I usually use the same account I’m using to connect in the next step.
This is the user account (or account alias) authorized to connect to the mail server in question.
This is the password associated with the account in the previous step.


This password is in plain text!  You MUST control access to this file to prevent disclosing your password to unintended third-parties.  You can use tools like GNOME keyring (requires you to have GNOME installed) or GPG-tools to encrypt this password but, I find encrypting the password causes problems including prompts that require user-intervention which is useless on an unattended system.  I’ll cover how to restrict file access later in this article, but if you want to use an encrypted password you’re on your own!

Specify a default account

Whether you have one or more account profiles set up in the previous section, you need to let msmtp know what to use if no sending account is explicitly specified (which will be pretty much always in our use-case).

## Set default account
account default
aliases /etc/msmtp_aliases

This is the profile name of the account profile in the previous section you want to use as the default.  This profile’s settings will be used unless msmtp is told to use something different (using the –from or –account switches on the invoking command line… not covered in this article).
This is a pointer to a list of account aliases.  We’ll cover this in more detail in the next section, but suffice to say this allows you to specify a short username and msmtp will resolve that to a proper email address.  NOTE:  Although we are not using sendmail in this example, you should NOT use /etc/aliases as the name of your alias file to avoid confusion with the sendmail version of the alias file.  That’s why I chose the more cumbersome msmtp_aliases as my filename.

Create the configuration file

Now that you understand what’s going on, let’s actually create the configuration file so msmtp can use it.

  1. Open a new file called msmtprc in your favourite text editor, I like nano:
    nano /etc/msmtprc
  2. Construct your setup based on the example given in the previous section.  You can get the most up-to-date version of my setup here and you can copy/paste.  Save your configuration file.
  3. msmtp is NOT a service or anything, so the new configuration is read the next time (and every time) you call the program.  There is no service to restart to apply changes.

The alias file

The alias file allows you to set up pointers for msmtp to map usernames to email addresses.  Based on our configuration file that we just created, we’ll create this file at ‘/etc/msmtp_aliases‘.  This is the alias file I use in setups such as we’re doing here.

root: [email protected]
default: [email protected]

You might be familiar with the aliases file used by sendmail.  This is NOT the same thing.  That’s why I suggest naming it something different to avoid confusion with the much more popular sendmail version of this file.

The above file (which is usually all you need) tells msmtp that if the destination address is ‘root’ then send it to [email protected].  If a name is provided that does not resolve on its own and does not match anything else in this file, then use the ‘default’ entry of [email protected] as the destination.  So, you could add a line like

root: [email protected]
postmaster: [email protected]
default: [email protected]

and then anytime you told msmtp to send to ‘postmaster’ it would automatically resolve that to [email protected].  If you want to set up additional aliases, that’s up to you depending on your particular setup.

msmtprc permissions and symlinking


As I mentioned earlier, your msmtprc configuration file has the email password in plain-text.  This is not good.  Now, most programs using msmtp to send out status reports will be running as root so you could just lock that file out to root access only.  You can do that by typing the following:

chmod 600 /etc/msmtprc

That will restrict read/write access to root only and grant no permissions whatsoever to any other account.  If that’s sufficient for your needs then you’re good to go onto testing.  If you need other accounts to access msmtp to send email, then you’ll have to make a group and give it permission to read the configuration file and, thus, the email password.  You can do that like this:

groupadd msmtp
usermod -aG msmtp username

where username is the name of the account you want to add to the newly created msmtp group.  Then type the following:

chgrp msmtp /etc/msmtprc
chmod 640 /etc/msmtprc

Now any member of the group msmtp can read the configuration file, only root can change it, and no other users can even see it.


Most programs will expect to use sendmail or some variant to send status reports (fail2ban, logwatch, etc.)  They most likely are not looking for msmtp.  That’s why we installed msmtp-mta in the very first step… it fools everyone into thinking sendmail is installed  😉

msmtp-mta creates a symlink to msmtp with the name ‘sendmail’ so it gets invoked whenever a program calls sendmail.  For your reference, and so you can check it out for yourself, that symlink is at /usr/sbin/sendmail.  You’ll see that it points to msmtp.

So, why install msmtp-mta instead of just doing the symlink yourself?  The best reason is because msmtp-mta tells the system that an MTA is installed.  That way other programs (like logwatch) don’t try to install MTA’s like postfix or exim which is what you wanted to avoid in the first place, right?


Ok, nice work so far!  Now it’s time to see the fruits of our labour!  First, let’s do a nice simple test where everything is spelt out for msmtp:

sendmail [email protected]
(o)Subject: This is a test message
(o)This is our first test message from msmtp!

Ok, so you’re typing the first line, replacing [email protected] with an address you can actually check, and pressing the    key at the end of each line.  The “Subject:” has to start with a capital “S” and include the colon and space after it.  Note also the blank line after your text, this is a standard convention but not strictly required.  To send your message, press <control-d> and msmtp will exit and send the message.  You can confirm/check this by looking at the log file (see why it’s important to have logs?)

tail /var/log/msmtp.log

You should see that the message was successfully queued for delivery with exitcode=EX_OK.  Now check the email account you emailed and make sure it’s delivered.  All good?  If so, let’s move on to another test:

sendmail root
(o)Subject: Testing aliases
(o)Another test message!

This time, we’re asking msmtp to read our alias file and resolve ‘root’ to whatever address you entered as the destination.  If it doesn’t work or throws an error, re-check your alias file.  A lot of programs will simply use ‘root’ as their destination, so this alias is pretty important.  Ready for the final test?

sendmail abcd
(o)Subject: Testing aliases
(o)Another test message!

Finally, we test msmtp with an alias that we didn’t define.  You’ll see that it simply uses the ‘default’ entry in our aliases file and sends mail there.  This is super-useful for programs that send to some account you didn’t plan for but still want to see the output.

Final thoughts

That’s it!  You have set up a simple, lightweight, mail relay system that can allow your programs to email you notifications, status updates or really anything including attachments!  The configuration file (and thus, access to the program) is also secured against unauthorized users.  I hope it’s useful to you, I use it on all of my mini-servers and virtual machines.  Thanks for reading my techie-thoughts on this issue. Have any comments? Suggestions? Want to add your tips? Things you want me to cover in a future article? Comment below!

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Close Menu