Charles Gutjahr

Melbourne, Australia

Adding a catchall to OS X Server Mail

22 Nov 2015 — a 3 minute read on tech

OS X Server 5 provides very few options for its inbuilt mail server, and does not provide an apparent way to configure a catchall — an inbox that receives all email sent to your domain. Catchalls risk being spammed, but catchalls are still valuable if you use a different email address for every website – as I do.

Fortunately the mail server in OS X Server is powered by Postfix, an open-source mail transfer agent that has plenty of options, including support for catchalls. I couldn't find another guide on how to do this, so here is mine:


Create a new Postfix virtual alias file with the catchall definition — don't try to edit the one OS X Server generates — then use Apple's serveradmin tool to change the Postfix virtual_alias_maps setting to include both your virtual alias file and the one generated by OS X Server.

Step-by-step guide

1. Choose a user

You need to pick one user that the catchall delivers to. You can choose your normal user if you like, but I recommend that you create a new user which is dedicated to receiving catchall email. That allows you to easily separate important email sent directly to you from the unimportant email your catchall will likely get.

For my example, I created a user called catchall.

2. Create a virtual users file

Postfix catchalls are normally configured in a virtual users file, and a standard installation of OS X Server 5 includes such a file in /Library/Server/Mail/Config/postfix/virtual_users. However OS X Server controls that file and will overwrite it whenever it chooses, so you cannot configure your catchall in here without the risk of it being lost.

Instead, use Terminal to create a new file called virtual_catchall in the same folder:

$ sudo nano /Library/Server/Mail/Config/postfix/virtual_catchall

Add line for each catchall that you want. Write your domain name (with an @ prefix) first, then a tab, then the name of the user you chose to receive the catchall emails. So if your domain is and your user catchall then write this in your file:	catchall

If you're using nano to edit the file, type Ctrl-O, Return, Ctrl-X to save and close the file.

3. Compile the virtual users file

Postfix does not read your new file directly, but instead will read a compiled binary version of it. To produce that, run postmap:

$ sudo postmap /Library/Server/Mail/Config/postfix/virtual_catchall 

4. Update OS X Server's configuration

The final step is to tell OS X Server to use your new virtual_catchall file in addition to the one that already exists. Again, you cannot edit the Postfix configuration files directly because OS X Server will overwrite them. Instead in this case you must use Apple's serveradmin tool.

First check what your current virtual_alias_maps setting is by looking at the main Postfix config file:

$ grep "^virtual_alias_maps" /Library/Server/Mail/Config/postfix/

By default it should be:

virtual_alias_maps = $virtual_maps hash:/Library/Server/Mail/Config/postfix/virtual_users

You need to take that existing setting and your catchall file onto the end. The critical thing is to use serveradmin to do that instead of editing the file directly:

$ sudo serveradmin settings mail:postfix:virtual_alias_maps = $virtual_maps hash:/Library/Server/Mail/Config/postfix/virtual_users hash:/Library/Server/Mail/Config/postfix/virtual_catchall

OS X Server will immediately apply the changes to Postfix, and your catchall should now be accepting email. It is worth checking that the main Postfix config file was updated correctly, ie:

$ grep "^virtual_alias_maps" /Library/Server/Mail/Config/postfix/

This time you should see something like:

virtual_alias_maps = hash:/Library/Server/Mail/Config/postfix/virtual_users hash:/Library/Server/Mail/Config/postfix/virtual_catchall

I notice that the $virtual_maps setting disappeared on my system when I did this. I don't know why that is, but given that its loss didn't seem to cause problems I haven't looked into it.

The final test is simple: just email any random email address @ your domain and you should see it arrive in your catchall inbox!

© 2024 Charles Gutjahr