Pigeon

Open source mail template compositor and router

Pigeon composites mail with a simple template system.

Pigeon uses standard markup language and template markup language to composite templates.

Distribution

Pigeon is distributed as open source and without license restriction. Information about the license is referenced in the included document: license.txt. Information about development is referenced in the included documents: notice.txt, version.txt.

Pigeon 0.2.2 is the latest version and is distributed as open source code.

Compilation

Pigeon is written in the Go programming language and depends on the standard library to compile. Go is compatible with common server operating systems and processor architectures. Pigeon is developed and supported on select systems: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64.

Pigeon compiles with different options: test, run, build, clean, install. The compile script is optional and automates the compile process.

% ./compile.sh

Operation

Pigeon is operated through a command line interface. The default path is /usr/local/bin/pigeon. The default paths can be changed with command options.

For security purposes, the process should be restricted to a dedicated pigeon user and pigeon group on the system.

Help

Print the help document.

% pigeon -help

Version

Print the version number.

% pigeon -version

Cache

Set the template cache mode. For performance purposes, the template cache is recommended.

% pigeon -cache

Verbose

Set the verbose log mode. For security purposes, the verbose log is not recommended.

% pigeon -verbose

Input Log

Set the standard input log file path. The default path is /usr/local/var/log/pigeon/input.log.

% pigeon -log-input path

Output Log

Set the standard output log file path. The default path is /usr/local/var/log/pigeon/output.log.

% pigeon -log-output path

Error Log

Set the standard error log file path. The default path is /usr/local/var/log/pigeon/error.log.

% pigeon -log-error path

Configuration

Set the configuration file path. The default path is /usr/local/etc/pigeon.cfg.

% pigeon -cfg path

Configuration

Pigeon is intended to operate behind a reverse proxy. For security purposes, the configuration file should be restricted to a dedicated pigeon user and pigeon group on the system.

Global Configuration

The global configuration section defines: server.

Define multiple servers for concurrent server processes.

{
  "server": [
    { ... },
    { ... }
  ]
}

Server Configuration

The server configuration section defines: hostname, port, template html extension, template txt extension, template root, mail hostname, mail port, mail username, mail password.

{
  "hostname": "localhost",
  "port": "0000",
  "template_extension_txt":  ".txt.go",
  "template_extension_html": ".html.go",
  "template_root": "/usr/local/var/www/example/",
  "mail": {
    "hostname": "localhost",
    "port": "0000",
    "authentication": {
      "username": "example",
      "password": "example"
    }
  }
}

Template

Pigeon combines text/plain and text/html templates into a multipart/alternative template.

Templates are a combination of standard markup language and the template markup language. If templates include comments, the comments are removed when the templates are processed.

File System

Pigeon will parse templates in the template root path. If the txt template and html template share the same name, both templates will be combined into a multipart template.

/example/avocado.html.go
/example/avocado.txt.go
/example/orchid.html.go
/example/orchid.txt.go

Template

The txt template and html template use the same template markup language.

{{define "content"}}
Hello {{template "firstname"}}
This is example content.
{{end}}
{{define "content"}}
<html>
  <div>Hello {{template "firstname"}}</div>
  <div>This is example content.</div>
</html>
{{end}}

Interface

Pigeon is controlled through a programming interface. The interface examples are provided in the Javascript programming language.

Request Message

The request message function will pass message data to the mail server.

function requestMessage(data) {
  fetch("https://localhost/pigeon", {
    method: "POST",
    headers: {
      "Accept": "application/json; charset=utf-8",
      "Content-Type": "application/json; charset=utf-8"
    },
    body: JSON.stringify(data)
  })
}

Generate Message

The generate message function will register different request modes and pass the generated message to the request message function.

function generateMessage(mode) {
  switch (mode) {
    case "example":
      requestMessage({
        from: {
          name:    `${name}`,
          address: `${address}`
        },
        to: {
          name:    `${name}`,
          address: `${address}`
        },
        title:   `${title}`,
        message: `${message}`
      });
      break;
    default:
      return null;
      break;
  }
}