Home

Awesome

[!IMPORTANT] Hi, my name is Philipp and I am one of the contributors to this project. Sadly it seems as if the original owner has abandonded go-guerilla. As I think there are still some nice things to do with it, and there might be some issues here and there, I have decided to revive this project.

I've already mirrored the repository to https://github.com/phires/go-guerrilla as I have not complete full access to this repo and don't know if it will disappear at some point. I will also try to migrate all further relevant informations (e.g. Wiki and Issues) over to the new repo.

If the original owner decides to come back I'll glady hand over full control of the projekt back to him. This should by no means be misinterpreted as a "hostile takeover" or anything. I just want to get this mighty fine piece of software back to speed and give it some further development.

-- 2023-08-31 Philipp

Latest: v1.6.1, tagged on Dec 28, 2019 (Pull requests from #129 to #203)

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

Backend Features

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 Dep to manage dependencies. If you have dep installed, just run dep ensure as usual.

You can also run $ go get ./.. if you don't want to use dep, 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 should use the dep ensure command to get all dependencies, as Go-Guerrilla uses dep for dependency management.

Otherise, $ go get ./... should work if you're in a hurry.

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:

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

ProcessorDescription
CompressorSets a zlib compressor that other processors can use later
DebuggerLogs the email envelope to help with testing
HasherProcesses each envelope to produce unique hashes to be used for ids later
HeaderAdd a delivery header to the envelope
HeadersParserParses MIME headers and also populates the Subject field of the envelope
MySQLSaves the emails to MySQL.
RedisSaves the email data to Redis.
GuerrillaDbRedisA '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.

ProcessorDescription
MailDirSave emails to a maildir. MailDiranasaurus is an example project
FastCGIDeliver email directly to PHP-FPM or a similar FastCGI backend.
WildcardProcessorUse 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 TLS/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!