Mini SMTP server written in golang
Branch: master
Clone or download
Latest commit cb55034 Jan 30, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
backends fix typo in sql query Jan 30, 2019
cmd/guerrillad Code style fixes (#131) Jan 30, 2019
log Code style fixes (#131) Jan 30, 2019
mail Code style fixes (#131) Jan 30, 2019
mocks Code style fixes (#131) Jan 30, 2019
response Code style fixes (#131) Jan 30, 2019
tests Code style fixes (#131) Jan 30, 2019
.gitignore More backends refactoring (#71) Mar 21, 2017
.travis.gofmt.sh revise and optimise guerrilla-db-redis backend (#50) Jan 22, 2017
.travis.yml Issue #28 - add new TLS configuration options (#110) May 28, 2018
GoGuerrilla.png add illustration Nov 13, 2012
LICENSE - Reload config on SIGHUP Jul 1, 2016
Makefile Fixes issue #101 - Gateway Timeout deadlock. (#102) Mar 8, 2018
README.md Fix a typo (#117) Jul 5, 2018
api.go Code style fixes (#131) Jan 30, 2019
api_test.go Code style fixes (#131) Jan 30, 2019
client.go Code style fixes (#131) Jan 30, 2019
config.go Code style fixes (#131) Jan 30, 2019
config_test.go Code style fixes (#131) Jan 30, 2019
event.go update event bus to the latest interfaces recently introduced in this… Mar 22, 2017
glide.lock More strict MAIL and RCPT command parsing. Addresses issue #120 (#129) Jan 6, 2019
glide.yaml Redis: provide a generic interface, import redigo optionally via cmd/… Aug 22, 2018
goguerrilla.conf.sample Issue #28 - add new TLS configuration options (#110) May 28, 2018
guerrilla.go Code style fixes (#131) Jan 30, 2019
guerrilla_notunix.go Code style fixes (#131) Jan 30, 2019
guerrilla_unix.go Code style fixes (#131) Jan 30, 2019
models.go Code style fixes (#131) Jan 30, 2019
pool.go Code style fixes (#131) Jan 30, 2019
server.go Code style fixes (#131) Jan 30, 2019
server_test.go Code style fixes (#131) Jan 30, 2019
tls_go1.8.go Issue #28 - add new TLS configuration options (#110) May 28, 2018
version.go Huge refactor: backends, package layout, ... Nov 7, 2016

README.md

Build Status

Breaking change: The structure of the config has recently changed to accommodate more advanced TLS settings.

Go-Guerrilla SMTP Daemon

A lightweight SMTP server written in Go, made for receiving large volumes of mail. To be used as a package in your Go project, or as a stand-alone daemon by running the "guerrillad" binary.

Supports MySQL and Redis out-of-the-box, with many other vendor provided processors, such as MailDir and even FastCGI! See below for a list of available processors.

Go Guerrilla

What is Go-Guerrilla?

It's an SMTP server written in Go, for the purpose of receiving large volumes of email. It started as a project for GuerrillaMail.com which processes millions of emails every day, and needed a daemon with less bloat & written in a more memory-safe language that can take advantage of modern multi-core architectures.

The purpose of this daemon is to grab the email, save it, and disconnect as quickly as possible, essentially performing the services of a Mail Transfer Agent (MTA) without the sending functionality.

The software also includes a modular backend implementation, which can extend the email processing functionality to whatever needs you may require. We refer to these modules as "Processors". Processors can be chained via the config to perform different tasks on received email, or to validate recipients.

See the list of available Processors below.

For more details about the backend system, see the: Backends, configuring and extending page.

License

The software is using MIT License (MIT) - contributors welcome.

Features

Main Features

  • Multi-server. Can spawn multiple servers, all sharing the same backend for saving email.
  • Config hot-reloading. Add/Remove/Enable/Disable servers without restarting. Reload TLS configuration, change most other settings on the fly.
  • Graceful shutdown: Minimise loss of email if you need to shutdown/restart.
  • Be a gentleman to the garbage collector: resources are pooled & recycled where possible.
  • Modular Backend system
  • Modern TLS support (STARTTLS or SMTPS).
  • Can be used as a package in your Go project. Get started in just a few lines of code!
  • Fuzz tested. Auto-tested. Battle Tested.

Backend Features

  • Arranged as workers running in parallel, using a producer/consumer type structure, taking advantage of Go's channels and go-routines.
  • Modular backend system structured using a decorator-like pattern which allows the chaining of components (a.k.a. Processors) via the config.
  • Different ways for processing / delivering email: Supports MySQL and Redis out-of-the box, many other vendor provided processors available.

Roadmap / Contributing & Bounties

Pull requests / issue reporting & discussion / code reviews always welcome. To encourage more pull requests, we are now offering bounties.

Take a look at our Bounties and Roadmap page!

Getting started

(Assuming that you have GNU make and latest Go on your system)

Dependencies

Go-Guerrilla uses Glide to manage dependencies. If you have glide installed, just run glide install as usual.

You can also run $ go get ./.. if you don't want to use glide, and then run $ make test to ensure all is good.

To build the binary run:

$ make guerrillad

This will create a executable file named guerrillad that's ready to run. See the build notes for more details.

Next, copy the goguerrilla.conf.sample file to goguerrilla.conf.json. You may need to customize the pid_file setting to somewhere local, and also set tls_always_on to false if you don't have a valid certificate setup yet.

Next, run your server like this:

$ ./guerrillad serve

The configuration options are detailed on the configuration page. The main takeaway here is:

The default configuration uses 3 processors, they are set using the save_process config option. Notice that it contains the following value: "HeadersParser|Header|Debugger" - this means, once an email is received, it will first go through the HeadersParser processor where headers will be parsed. Next, it will go through the Header processor, where delivery headers will be added. Finally, it will finish at the Debugger which will log some debug messages.

Where to go next?

Use as a package

Go-Guerrilla can be imported and used as a package in your Go project.

Quickstart

1. Import the guerrilla package

import (
    "github.com/flashmob/go-guerrilla"
)

You may use $ go get ./... to get all dependencies, also Go-Guerrilla uses glide for dependency management.

2. Start a server

This will start a server with the default settings, listening on 127.0.0.1:2525

d := guerrilla.Daemon{}
err := d.Start()

if err == nil {
    fmt.Println("Server Started!")
}

d.Start() does not block after the server has been started, so make sure that you keep your program busy.

The defaults are:

  • Server listening to 127.0.0.1:2525
  • use your hostname to determine your which hosts to accept email for
  • 100 maximum clients
  • 10MB max message size
  • log to Stderror,
  • log level set to "debug"
  • timeout to 30 sec
  • Backend configured with the following processors: HeadersParser|Header|Debugger where it will log the received emails.

Next, you may want to change the interface (127.0.0.1:2525) to the one of your own choice.

API Documentation topics

Please continue to the API documentation for the following topics:

Use as a Daemon

Manual for using from the command line

Other topics

Email Processing Backend

The main job of a Go-Guerrilla backend is to validate recipients and deliver emails. The term "delivery" is often synonymous with saving email to secondary storage.

The default backend implementation manages multiple workers. These workers are composed of smaller components called "Processors" which are chained using the config to perform a series of steps. Each processor specifies a distinct feature of behaviour. For example, a processor may save the emails to a particular storage system such as MySQL, or it may add additional headers before passing the email to the next processor.

To extend or add a new feature, one would write a new Processor, then add it to the config. There are a few default processors to get you started.

Included Processors

Processor Description
Compressor Sets a zlib compressor that other processors can use later
Debugger Logs the email envelope to help with testing
Hasher Processes each envelope to produce unique hashes to be used for ids later
Header Add a delivery header to the envelope
HeadersParser Parses MIME headers and also populates the Subject field of the envelope
MySQL Saves the emails to MySQL.
Redis Saves the email data to Redis.
GuerrillaDbRedis A 'monolithic' processor used at Guerrilla Mail; included for example

Available Processors

The following processors can be imported to your project, then use the Daemon.AddProcessor function to register, then add to your config.

Processor Description
MailDir Save emails to a maildir. MailDiranasaurus is an example project
FastCGI Deliver email directly to PHP-FPM or a similar FastCGI backend.
WildcardProcessor Use wildcards for recipients host validation.

Have a processor that you would like to share? Submit a PR to add it to the list!

Releases

Current release: 1.5.1 - 4th Nov 2016

Next Planned release: 2.0.0 - TBA

See our change log for change and release history

Using Nginx as a proxy

For such purposes as load balancing, terminating TLS early, or supporting SSL versions not supported by Go (highly not recommended if you want to use older SSL versions), it is possible to use NGINX as a proxy.

Credits

Project Lead:

Flashmob, GuerrillaMail.com, Contact: flashmob@gmail.com

Major Contributors:

Thanks to:

... and anyone else who opened an issue / sent a PR / gave suggestions!