Skip to content

Instantly share code, notes, and snippets.

@raelgc

raelgc/Email Server (Linux, Unix, Mac).md

Last active December 4, 2025 20:10
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save raelgc/6031274 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save raelgc/6031274 to your computer and use it in GitHub Desktop.
Download ZIP
Setup a Local Only SMTP Email Server (Linux, Unix, Mac)
Raw
Email Server (Linux, Unix, Mac).md

Setup a Local Only SMTP Email Server (Linux, Unix, Mac)

1 - Point localhost.com to your machine

Most of programs will not accept an email using just @localhost as domain. So, edit /etc/hosts file to make the domain localhost.com point to your machine, including this content to the file:

127.0.0.1 localhost.com

2 - Install Postfix

Fedora/CentOS/RHEL: sudo yum install postfix

Ubuntu: sudo apt-get install postfix

MacOSX: Postfix is already installed by default.

3 - Configure Postfix to Local only

  • During postfix install process, the configure text dialog will display five options:

    General type of mail configuration: 

No configuration
Internet Site
Internet with smarthost
Satellite system
Local only

  • Select "Local Only".

  • For the domain name, use the default suggested and finish the install.

4 - Configure a Catch-all Address

Enabling this, you can use any email address ending with "@localhost" or "@localhost.com".

Example: here, my unique account is [email protected]. But while testing systems, I can use any address like [email protected], [email protected], etc, because all will be redirected to [email protected]

  • If not exists, create file /etc/postfix/virtual: sudo nano /etc/postfix/virtual
  • Add the following 2 lines content, replacing <your-user> with your Unix user account:
@localhost <your-user>
@localhost.com <your-user>
  • Save and close the file.
  • Configure postifx to read this file:
    • Open /etc/postfix/main.cf: sudo nano /etc/postfix/main.cf
    • And check if this line is enabled, or add it if not exists: virtual_alias_maps = hash:/etc/postfix/virtual
  • Activate it: sudo postmap /etc/postfix/virtual
  • Reload postfix: sudo systemctl restart postfix
  • If you're under non systemd distro, like Ubuntu 14.04, service restart command probably is: sudo service postfix reload

5 - Install Thunderbird

Ubuntu: sudo apt-get install thunderbird

6 - Configure Thunderbird

  • Skip the welcome screen (click in the button to use existing accounts);
  • Click in the Settings button at top right (similar to Chrome settings) then click on Preferences > Account Settings
  • Under Account Actions choose "Add Other Account"
  • Select "Unix Mailspool (Movemail)"
  • Your account will be <your-user>@localhost (of course, replace <your-user> with your user account). Don't use <your-user>@(none), use <your-user>@localhost
  • Ingoing and Outgoing server will be: localhost
  • Restart (close and reopen) Thunderbird.

7 - Start your Mail Spool file

  • This step have two purposes: test your install and stop the Unable to locate mail spool file. message.
  • Using Thunderbird, send new email to <your-user>@localhost, replacing <your-user> with your user account
  • Click on "Get Mail"
  • Test catch-all: send new email to averagejoe@localhost
  • Click on "Get Mail" and you'll see the message at Inbox.
@XGamerYU
Copy link

XGamerYU commented Jan 23, 2019 •
edited
Loading

Hello there, thanks for the tutorial.
I have an issue... I setup everything as needed, port is 25... outgoing server is localhost , I can send the mail without troubles, to me, but whenever I try to get the mail, it says "Unable to locate mail spool file" - no matter what I do... is there anything I can do... thanks in advance!

EDIT:
I tried doing it on a virtual machine and it worked without any troubles. Thanks a lot for the guide, also, had to use port 25 on the outgoing server. Thanks.

@davidpustai
Copy link

davidpustai commented Mar 21, 2019

Thanks a lot! Finally found a useful article on this topic. :)

@AzirGar
Copy link

AzirGar commented Mar 21, 2019

I have a question, How do I configure the server so that it has Internet access, or can send to other types of domains such as gmail, outlook. etc

@chrispito
Copy link

chrispito commented May 7, 2019

Thank's very much for this short tuto.

@lrusik
Copy link

lrusik commented Aug 1, 2019

Clear and simple! Thanks a lot

@aqeel-ahmad-plc
Copy link

aqeel-ahmad-plc commented Sep 19, 2019

Clearly documented, just follow it step by step and it works.

Copy link

ghost commented Jan 4, 2020

works flawlessly (ubuntu 19.10) Thank you! :)

@erickclasen
Copy link

erickclasen commented Mar 24, 2020 •
edited
Loading

Works great. I really liked the instructions, very easy to set up. I was glad I found this as, I thought it might be tricky and with these instructions it was a few minutes on each machine.

I tried it on a desktop and a server.

Server
On the server, which only has a CLI, I wound up using mail instead of T-bird, installed via sudo apt-get install mailutils
It can be tested by sending a message to yourself by using...
mail -s "test" (your user name)@localhost
It works great to get the CRON messages on the machine.
Just type mail and you get a CLI email list. mail basics are, q to quit, m to compose, enter and spacebar to move through messages. Entering question mark ?, brings up command help.

Desktop Install
One gotcha that caught me is that I already had T-bird installed and therefore it had a default SMTP server already. For me this required what I would call step 6A to add a local STMP server.
6A. In the pane above "Account Actions" scroll, using the bar to the bottom "Outgoing Server (SMTP)".
Click Add
For description I wrote Local SMTP
Server Name: localhost
Port: 25
Username : (the user name)@localhost
Authentication Method: Password, transmitted insecurely
Connection Security: None

Then I went back into the account settings for the mail set up in step 6 and set the Outgoing Server (SMTP) to the Local SMTP

Also in /etc/hosts you can put in localhost.com as a alias and it works fine, like this...
127.0.0.1 localhost localhost.com

@teezzan
Copy link

teezzan commented Apr 15, 2020

Awesome... Thanks... Port 25 is important..;)

@Uysim
Copy link

Uysim commented Apr 30, 2020

Anyone manage to have it work on Mac. I got this error

An error occurred while sending mail. 
The mail server responded: 530 5.7.0 Must issue a STARTTLS command first. 
Please verify that your email address is correct in your account settings and try again.

@raelgc
Copy link
Author

raelgc commented May 1, 2020

@Uysim It appears that your server (or client) are using the secure port instead of port 25. Additionally, check the authentication settings.

@popovserhii
Copy link

popovserhii commented Jun 12, 2020

For testing you can also use next command:
echo "This is the body of the email" | mail -s "This is the subject line" your_email_address

After that, go to Thunderbird and click Get Messages

@ombak
Copy link

ombak commented Jul 23, 2020

I follow this tutorial in Debian 10, but when I try to use thunderbird I always get Unable to locate mail spool file.

This my /etc/host

127.0.0.1 localhost
127.0.0.1 localhost.com

My hostname:

localhost

This my /etc/postfix/main.cf

smtpd_relay_restrictions = permit_mynetworks permit_sasl_authenticated defer_unauth_destination
myhostname = localhost.localdomain
alias_maps = hash:/etc/aliases
alias_database = hash:/etc/aliases
myorigin = /etc/mailname
mydestination = example.com, $myhostname, localhost.localdomain, localhost.localdomain, localhost
relayhost = 
mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128
mailbox_size_limit = 0
recipient_delimiter = +
inet_interfaces = loopback-only
default_transport = error
relay_transport = error
inet_protocols = all

Thanks

@rpopov
Copy link

rpopov commented Nov 19, 2020

Thank you! Worked perfectly well

@SukeshiniR
Copy link

SukeshiniR commented Feb 4, 2021

I'm getting an error regarding the SMPT settings. It reads

Sending of the message failed.
The message could not be sent because connecting to Outgoing server (SMTP) localhost failed. The server may be unavailable or is refusing SMTP connections. Please verify that your Outgoing server (SMTP) settings are correct and try again.

Any idea how I can test what is wrong here? When I use for example PHP to send mail, I do receive it, but when I use Thunderbird to send mail, I cannot send it.

SMTP settings in Thunderbird are:

Server Name localhost
Port 587
Connection security none
Authentication method Password, transmitted insecurely
User Name My user name

EDIT Changing the port number to 25 fixed it. While I was typing this all of a sudden I realized :). Just leaving this message here in case anyone else runs into this problem.

Thank you. This worked for me!

@rlogwood
Copy link

rlogwood commented Feb 19, 2021

Really appreciate this, thank you! I'm running Ubuntu 20.04 LTS and Thunderbird Mail 1:68.10.0+build1-0ubuntu0.20.04.1.

To add to previous comments from other current users of Thunderbird mail, like myself, I've enclosed a screen shot of my outgoing SMTP Server for the postfix server account created as per the instructions. Replace the blue splat with your account name :)

image

@DoctorSubtilis
Copy link

DoctorSubtilis commented Mar 11, 2021

Thank you, but I have a problem, both in receiving and in sending e-mail.
Sending an e-mail (with another account) to duns@localhost I get this error message:

DNS Error: 765891 DNS type 'mx' lookup of localhost responded with code NXDOMAIN Domain name not found: localhost

Sending an email with localhost I get this message
An error occurred while sending mail. The mail server responded: 5.1.1 <mymail@mydomain>: Recipient address rejected: mydomain. Please check the message recipient "<mymail@mydomain>" and try again.

my main.cf postfix:

readme_directory = no
compatibility_level = 2

smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem
smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
smtpd_tls_security_level=may

smtp_tls_CApath=/etc/ssl/certs
smtp_tls_security_level=may
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache


smtpd_relay_restrictions = permit_mynetworks permit_sasl_authenticated defer_unauth_destination
myhostname = duns-neon.home
alias_maps = hash:/etc/aliases
alias_database = hash:/etc/aliases
virtual_alias_maps = hash:/etc/postfix/virtual
mydestination = $myhostname, duns-neon, localhost.localdomain, localhost
relayhost =
mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128
mailbox_size_limit = 0
recipient_delimiter = +
inet_interfaces = loopback-only
default_transport = error
relay_transport = error
inet_protocols = all

@emgrasso
Copy link

emgrasso commented Jul 24, 2021

The instructions are clear for Postfix, but current Thunderbird versions are fussy.
I'm on Ubuntu 20.04, with Thunderbird 78.11.0. netstat indicates that postfix is listening on port25.
But Thunderbird says it can't connect to the account for incoming messages
Thunderbid seemd to want to prepend a . to the server names: I assumed since that needs to be removed for the SMTP settings, the same should hold for the IMAP. Is there a combination of port and security settings that works?
143, connection security: none, password transmitted insecurely does not seem to work. Thunderbird is also not prompting for a password, but it doesn't react well to being told to remember an initial password either.

@Applebois
Copy link

Applebois commented Jul 28, 2021

Thanks,
This is really good post !

@idea-lei
Copy link

idea-lei commented Mar 15, 2022 •
edited
Loading

thanks for the tutorial.
but I could not find the correct option in section 6 -> Select "Unix Mailspool (Movemail)"
it was only one option "Newsgroup account"
how could I fix this? thx in advance

-------Edit-------
for users who does not find the "unix mailspool" option sam as me:
thunderbird has removed the "unix mailspool" support since version 91. if want to follow this instruction, install a older verison instead

@AlexDraeger
Copy link

AlexDraeger commented Oct 17, 2022 •
edited
Loading

First, thanks for this tutorial:)

thanks for the tutorial. but I could not find the correct option in section 6 -> Select "Unix Mailspool (Movemail)" it was only one option "Newsgroup account" how could I fix this? thx in advance

-------Edit------- for users who does not find the "unix mailspool" option sam as me: thunderbird has removed the "unix mailspool" support since version 91. if want to follow this instruction, install a older verison instea

another option is to simply show the mail textfile in thunderbirds local folders.
Notice that this is no elegant version but it seems that unix movemail will not be supported in the future

  1. Thunderbird: Right click on 'Local Folders' -> Settings. Copy your the 'Local Directory'-Path.
  2. Close Thunderbird
  3. Create a new Symlink via Terminal:
    NOTE: Eather escape the whitespace or keep your path (Local Directory) between quotation marks
ln -s /var/mail/<username> '<LOCAL DIRECTORY>'
  1. Change Permissions for /var/mail/<username> to 666 or 600
  2. You will find incoming mails in your Local Folders/'username'

Source: https://www.it-consulting-stahl.de/2022/06/zugriff-auf-lokale-mails-mit-thunderbird-91/

@raelgc
Copy link
Author

raelgc commented Jan 27, 2023

It appears that Thunderbird has plans to restore movemail someday in the future: https://bugzilla.mozilla.org/show_bug.cgi?id=1802145.

In this meanwhile, people is advising to use BetterBird.

@AlanCW
Copy link

AlanCW commented Feb 15, 2023

Since Unix Mailspool was removed in Thunderbird, a really great option is to install Betterbird 102.8.0-bb30 (14 February 2023). It is a much better implementation of Thunderbird that allows local mail.

https://www.betterbird.eu/

@ABBIDA21
Copy link

ABBIDA21 commented Nov 14, 2023

but im using just a server without a gui how can i do the step 6****

@nd-dew
Copy link

nd-dew commented Dec 8, 2023

got stuck on step 6, managed to get through it by installing Thunderbird version 45 (cause this tutorial was created around time version 45 was used).

@1egend78
Copy link

1egend78 commented Mar 8, 2024

Hi,
I am surprised that you are accessing emails from Postfix email server via Thunderbird client without installing Dovecot or Courier-IMAP which let the server listen on port 143 (IMAP) and 995 (POP3). The server is listening only port 25 (SMTP) with your configuration. I think it is an incomplete tutorial.

@raelgc
Copy link
Author

raelgc commented Mar 8, 2024

@1egend78 This is a tutorial only for development testing purposes on localhost. It's not intended to be a real email server. In this sense (be a real email server), yes, it's missing other steps.

@AlanCW
Copy link

AlanCW commented Nov 18, 2025 via email

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment