{"id":18849140,"url":"https://github.com/gesquive/dispatch","last_synced_at":"2025-04-14T08:42:09.489Z","repository":{"id":14531114,"uuid":"76690745","full_name":"gesquive/dispatch","owner":"gesquive","description":"A self-hosted mail forwarding API microservice","archived":false,"fork":false,"pushed_at":"2022-05-01T20:59:06.000Z","size":144,"stargazers_count":29,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-27T22:13:13.005Z","etag":null,"topics":["email","microservice","rest-api"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gesquive.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-16T22:47:36.000Z","updated_at":"2024-01-05T19:01:34.000Z","dependencies_parsed_at":"2022-08-07T08:00:20.961Z","dependency_job_id":null,"html_url":"https://github.com/gesquive/dispatch","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gesquive%2Fdispatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gesquive%2Fdispatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gesquive%2Fdispatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gesquive%2Fdispatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gesquive","download_url":"https://codeload.github.com/gesquive/dispatch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248849314,"owners_count":21171563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email","microservice","rest-api"],"created_at":"2024-11-08T03:18:30.033Z","updated_at":"2025-04-14T08:42:09.468Z","avatar_url":"https://github.com/gesquive.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dispatch\n[![Software License](https://img.shields.io/badge/License-MIT-orange.svg?style=flat-square)](https://github.com/gesquive/dispatch/blob/master/LICENSE)\n[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](https://pkg.go.dev/github.com/gesquive/dispatch)\n[![Build Status](https://img.shields.io/circleci/build/github/gesquive/dispatch?style=flat-square)](https://circleci.com/gh/gesquive/dispatch)\n[![Coverage Report](https://img.shields.io/codecov/c/gh/gesquive/dispatch?style=flat-square)](https://codecov.io/gh/gesquive/dispatch)\n[![Docker Pulls](https://img.shields.io/docker/pulls/gesquive/dispatch?style=flat-square)](https://hub.docker.com/r/gesquive/dispatch)\n\n\nA self-hosted mail forwarding web API server.\n\nThis program was created to provide a json-based email API for static sites. You could use any transactional mailing service and pay them a monthly fee, or stand up your own dispatch.\n\n## Installing\n\n### Compile\nThis project has only been tested with go1.17+. To compile just run `go install github.com/gesquive/dispatch@latest` and the executable should be built for you automatically in your `$GOPATH`. \n\nOptionally you can clone the repo and run `make install` to build and copy the executable to `/usr/local/bin/` with correct permissions.\n\n### Download\nAlternately, you can download the latest release for your platform from [github](https://github.com/gesquive/dispatch/releases).\n\nOnce you have an executable, make sure to copy it somewhere on your path like `/usr/local/bin` or `C:/Program Files/`.\nIf on a \\*nix/mac system, make sure to run `chmod +x /path/to/dispatch`.\n\n### Docker\nYou can also run dispatch from the provided [Docker image](https://hub.docker.com/r/gesquive/dispatch) and by providing a configuration file:\n\n```shell\ndocker run -d -p 2525:2525 -v $PWD/docker:/config gesquive/dispatch:latest\n```\n\nTo get the sample config working, you will need to configure the SMTP server and add target configs. \n\nFor more details read the [Docker image documentation](https://hub.docker.com/r/gesquive/dispatch).\n\n## Configuration\n\n### Precedence Order\nThe application looks for variables in the following order:\n - command line flag\n - environment variable\n - config file variable\n - default\n\nSo any variable specified on the command line would override values set in the environment or config file.\n\n### Config File\nThe application looks for a configuration file at the following locations in order:\n - `./config.yml`\n - `~/.config/dispatch/config.yml`\n - `/etc/dispatch/config.yml`\n\nCopy `pkg/config.example.yml` to one of these locations and populate the values with your own. Since the config contains a writable API token, make sure to set permissions on the config file appropriately so others cannot read it. A good suggestion is `chmod 600 /path/to/config.yml`.\n\nIf you are planning to run this app as a service, it is recommended that you place the config in `/etc/dispatch/config.yml`.\n\n### Targets\nTargets are defined as follows:\n```yaml\n# name is the unique name for this target (default value is the target filename)\n# name will show up in the subject of the email\nname: example\n# auth-token should be a unique random string of characters\nauth-token: f6uf9xvb@tze22O!KCZ7WExe\n# emails will be sent from\nfrom: dispatch@my-site.com\n# emails will be sent too\nto:\n  - admin@my-site.com\n  - personal@anywhere.com\n\ndefaults:\n  subject: \"site message\"\n  tag: \"no-tag\"\n\n```\n\nTargets should be named with the `.yml` extension and be placed in the directory defined by the `--target-dir` flag. By default this is `/etc/dispatch/targets-enabled`.\n\n#### Target Auth Tokens\nEach target requires a unique Auth token so incoming messages can be routed to the correct target. Without a unique auth tokens, messages will be routed incorrectly.\n\n#### Target Defaults\nAny key-values specified under the `defaults` variable will be used as the default for all incoming requests. Any values specified in either the payload or header will overwrite these values\n\n#### Request HTTP Headers\nIt is possible to specify a value for a request in the HTTP headers. Values specified in an HTTP header will always overwrite values specified through json. To specify a value through HTTP headers use the prefix `X-Dispatch-` with the variable name. For example, if you wanted to specify the `auth-token` through a HTTP header, simply post the json with the header `X-Dispatch-Auth-Token`\n\n#### Request Precedence Order\nValues for requests can be specified through an http request, request header or target default. The application takes values in the following order:\n - request header\n - request payload\n - target default\n\n So a variable value specified in an http request header will always override a value specified in the payload of an http request.\n\n### Environment Variables\nOptionally, instead of using a config file you can specify config entries as environment variables. Use the prefix `DISPATCH_` in front of the uppercased variable name. For example, the config variable `smtp-server` would be the environment variable `DISPATCH_SMTP_SERVER`.\n\n### Service\nThis application was developed to run as a service behind a webserver such as nginx, apache, or caddy.\n\nYou can use upstart, init, runit or any other service manager to run the `dispatch` executable. Example scripts for systemd and upstart can be found in the `pkg/services` directory. A logrotate script can also be found in the `pkg/services` directory. All of the configs assume the user to run as is named `dispatch`, make sure to change this if needed.\n\n## Usage\n\n```console\nRun a webserver that provides an json api for emails\n\nUsage:\n  dispatch [flags]\n\nFlags:\n  -a, --address string               The IP address to bind the web server too (default \"0.0.0.0\")\n      --check                        Check the config for errors and exit\n      --config string                Path to a specific config file (default \"./config.yml\")\n  -l, --log-file string              Path to log file (default \"/var/log/dispatch.log\")\n  -p, --port int                     The port to bind the webserver too (default 2525)\n  -r, --rate-limit string            The rate limit at which to send emails in the format 'inf|\u003cnum\u003e/\u003cduration\u003e'. inf for infinite or 1/10s for 1 email per 10 seconds. (default \"inf\")\n  -w, --smtp-password string         Authenticate the SMTP server with this password\n  -o, --smtp-port uint32             The port to use for the SMTP server (default 25)\n  -x, --smtp-server string           The SMTP server to send email through (default \"localhost\")\n  -u, --smtp-username string         Authenticate the SMTP server with this user\n      --target-auth-token string     Target auth token for an optional target\n  -t, --target-dir string            Path to target configs (default \"/etc/dispatch/targets-enabled\")\n      --target-from-address string   Target from address for an optional target\n      --target-name string           Target name for an optional target\n      --target-to-address strings    Target to address list for an optional target\n      --version                      Display the version info and exit\n```\n\nOptionally, a hidden debug flag is available in case you need additional output.\n```console\nHidden Flags:\n  -D, --debug                  Include debug statements in log output\n```\n\n## Examples\nTo send an email using dispatch, simply send a JSON formatted POST request to the `/send` endpoint. The format is as follows:\n```json\n{\n    \"auth-token\": \"\",\n    \"name\": \"\",\n    \"email\": \"\",\n    \"subject\": \"\",\n    \"message\": \"\",\n}\n```\n\n`auth-token` is the only required field. If not provided in the json as `auth-token` it must be passed through the HTTP Header `X-Dispatch-Auth-Token`. dispatch also checks to see if the `email` field is a valid email address.\n\n### Javascript example\n```javascript\n$(document).ready(function() {\n\n    // process the form\n    $('form').submit(function(e) {\n\n        // get the form data\n        var formData = {\n            'name'          : $('input[name=name]').val(),\n            'email'         : $('input[name=email]').val(),\n            'subject'       : $('input[name=subject]').val(),\n            'message'       : $('textarea[name=message]').val(),\n            'auth-token'    : $('input[name=auth-token]').val()\n        };\n\n        // process the form\n        $.ajax({\n            type        : 'POST',\n            url         : '/send', // the url where we want to POST\n            data        : formData,\n            dataType    : 'json', // what type of data do we expect back from the server\n            encode      : true\n        })\n            .done(function(data) {\n                // here we handle a successful submission\n                console.log(data);\n            });\n\n        // stop the form from refreshing the page\n        e.preventDefault();\n    });\n\n});\n```\n\n### CURL example\n```shell\ncurl -i -X POST -H \"Content-Type: application/json\" -H \"X-Dispatch-Subject: cmd email\" -d '{ \"auth-token\":\"qasZ1z6HfVPRCq1D0GQUpVB8\", \"name\":\"anon\", \"email\":\"test@dispatch.com\", \"message\":\"Hello!\"}' http://dispatch:7070/send\n```\n\n## Documentation\n\nThis documentation can be found at github.com/gesquive/dispatch\n\n## License\n\nThis package is made available under an MIT-style license. See LICENSE.\n\n## Contributing\n\nPRs are always welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgesquive%2Fdispatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgesquive%2Fdispatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgesquive%2Fdispatch/lists"}