server

README

dovel development home

_________                 ______
______  /________   _________  /
_  __  /_  __ \_ | / /  _ \_  / 
/ /_/ / / /_/ /_ |/ //  __/  /  
\__,_/  \____/_____/ \___//_/   

Welcome! This is the git repository of the dovel.email project, here you'll find the go code for the SMTP server.

Installing

Instructions can be found on our website.

Contributing

General instructions can be found on the git index page, to keep track of patches or bug reports use the mail link on the header of this page.

Thank you for taking your time.

Documentation

Overview

server is a SMTP server that is simple to setup and use.

The binary is the main server, this server is responsible to receive your emails and save them according to your hooks. As well as sending them.

Setting up your email server

Email works in a complex way, DNS records must match your server's configuration. This guide will try to give more detailed information in comparison with the website tutorial.

An email server typically listens on ports 25, 2525, 587 or 465 for mail exchange. But their use differ:

• 25: is the original SMTP port and first to be official by RFC.
• 465: is marked as deprecated.
• 587: is also official by RFC, this port is used for TLS encrypted mail.

The current recomendation is to use port 587. Dovel works with any port, and the value must be set in the port field of the config file. To configure this server see Config.

Server configuration

This section is dedicated to help you correctly run your dover server. The configuration is done using a single config file which should be located in $XDG_CONFIG_DIR/dovel/config.json which normaly expands to ~/.config/dovel/config.json. The structure of this config file is [model.Config]. See that doc for more details. The following example should be enough to receive emails:

{
	"Port": "2525",
	"Domain": "my.domain",
	"ReadTimeout": 30,
	"WriteTimeout": 30,
	"MaxMessageBytes": 5000000,
	"MaxRecipients": 5,
	"Certificate": "fullchain.pem",
	"PrivateKey": "privkey.pem"
}

Note that Certificate and PrivateKey are given so that your server can use TLS connections, this is desired for enhanced security. In cases where proxies are used in front of servers, for doing the TLS handshake, setting certificates here is not necessary.

Receiving emails

To receive email the MX record must be correctly set on your registrar, make sure it is pointing to your server where dover is running. Everytime dovel receives an email it searches for an executable file in $XDG_CONFIG_DIR/dovel/hooks/ named receive-DOMAIN, for the DOMAIN receiving the email and executes it passing the email in mbox format as standard input. Then it is up to the script to decide what to do. See the scripts repo for examples, one simple is given in the next section.

Hooks

A simple hook is a shell script that simply concatenates the received email to a .mbox file, e.g. to receive email for your domain create a file named receive-<DOMAIN> in the hooks folder with the following content:

#!/bin/sh
cat >> ~/mail/dovel.mbox

Be sure to make the file executable. Now whenever an email to the domain DOMAIN it will be appended to the ~/mail/dovel.mbox file, which you can later open and read.

Configuring DNS records

To receive emails you need to setup the MX record in your domain registrar, sending email is more complicated, some receiving servers only need the SPF and PTR records, some also need DKIM and DMARC, adjust according to your needs. Configuring DNS records is not the goal of this doc.

DKIM configuration

DKIM in dovel is handled in a per-user basis only for sending emails, for receiving emails it is up to the corresponding hook. This means that each user have to setup its DKIM key. Luckily this is simply pointing the key path in the User struct.

Sending email

Dovel also sends email, for that it needs a valid VaultFile path on the config. That means you need at least one user described on the json file. The format of that file is a JSON array of the [model.User] struct. Here's one example:

[
	{
		"Name": "user1@my.domain",
		"PrivateKey": "dkim.priv",
		"Password": "1234"
	}
]

This means the user1@my.domain is allowed to send emails, also as its DKIM key was passed it will be used to sign the email using the DKIM guidelines. This is optional.

You can use any email client to communicate with your dovel server. When an email comes from the domain configured, Dovel will known you want to send the email, and will check if the sending user is valid using the configured users, in positive case the email is sent, and the hook named send-<DOMAIN> for the domain used is run passing the sent email as input. The success of this hook does not impact one the sent email, it is mainly used for storing it.

Debuging your server

Dovel will issue debugging logs for the developer's convenience by setting the DEBUG environment variable to any non-empty value at the time the server is started, e.g.:

DEBUG=1 ./server