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

Verbose

Set the verbose process mode. The verbose mode should be false for security purposes. Set the verbose mode to true to print all process information.

The default mode is false.

% pigeon -verbose=boolean

Template Cache

Set the template cache mode. The cache mode should be true for performance purposes. Set the cache mode to false to parse template modifications.

The default mode is true.

% pigeon -cache=boolean

Input Log

Set the input log file path. The process will log standard input to the input log file. The process will generate the input log file when missing.

The default path is /usr/local/var/log/pigeon/input.log.

% pigeon -log-input=string

Output Log

Set the output log file path. The process will log standard output to the output log file. The process will generate the output log file when missing.

The default path is /usr/local/var/log/pigeon/output.log.

% pigeon -log-output=string

Error Log

Set the error log file path. The process will log standard error to the error log file. The process will generate the error log file when missing.

The default path is /usr/local/var/log/pigeon/error.log.

% pigeon -log-error=string

Configuration

Set the configuration file path. The process will generate the configuration file when missing.

The default path is /usr/local/etc/pigeon.cfg.

% pigeon -cfg=string

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"
    }
  }
}

Templates

Pigeon parses both template formats and combines them into a multipart message. The mail client determines which template format to present.

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 message.

/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}}

Events

Pigeon is controlled through an application programming interface. These examples are provided in the Javascript programming language.

Request Message

The message is sent and processed through the mail server.

curl https://localhost/pigeon \
--request POST \
--header "Accept: application/json; charset=utf-8" \
--header "Content-Type: application/json; charset=utf-8" \
--data '{"example": "example"}' \
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 message generator registers different message modes.

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