{"id":17354145,"url":"https://github.com/dovyski/pigeon","last_synced_at":"2025-03-27T13:24:27.681Z","repository":{"id":140596000,"uuid":"108121763","full_name":"Dovyski/pigeon","owner":"Dovyski","description":"Easy to use and hassle-free PHP microservice for sending e-mails via a REST API","archived":false,"fork":false,"pushed_at":"2017-10-27T08:12:58.000Z","size":61,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-01T17:44:10.875Z","etag":null,"topics":["e-mail","http","microservice","php","rest"],"latest_commit_sha":null,"homepage":"","language":"PHP","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/Dovyski.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-24T12:11:48.000Z","updated_at":"2021-04-09T06:59:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"746435f4-690e-44ef-87b9-19be1691279a","html_url":"https://github.com/Dovyski/pigeon","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dovyski%2Fpigeon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dovyski%2Fpigeon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dovyski%2Fpigeon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dovyski%2Fpigeon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dovyski","download_url":"https://codeload.github.com/Dovyski/pigeon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245851421,"owners_count":20682850,"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":["e-mail","http","microservice","php","rest"],"created_at":"2024-10-15T17:19:12.207Z","updated_at":"2025-03-27T13:24:27.650Z","avatar_url":"https://github.com/Dovyski.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"./img/pigeon.png\" align=\"right\" title=\"Pigeon\" /\u003e\n\n# Pigeon\n\nPigeon is an easy to use, hassle-free PHP microservice for sending e-mails via HTTP requests. It values simplicity above all, i.e. no database required, extremely easy and quick installation. It is intended for small, in-house projects that require e-mail sending capabilities.\n\n## Getting started\n\n### 1. Prerequisites\n\nYou need [PHP](https://php.net) and a web server to run Pigeon. If you indent to use its SMTP funcionality, you will need [composer](https://getcomposer.org/) and access to an SMTP server you can dispatch messages to.\n\n### 2. Installing\n\nClone Pigeon's repository in document root of your web server (e.g. `/var/www/`):\n\n```\ngit clone https://github.com/Dovyski/pigeon.git pigeon \u0026\u0026 cd pigeon\n```\n\nAt this point Pigeon is already ready for use. It is relying on the existing e-mail infra-instructure of the machine, i.e. PHP's `mail()` function.\n\n### 3. Installing SMTP dependencies (optional)\n\nIf you intend to use SMPT as a sending mechanism, you need to download a few dependencies. In the folder where you cloned Pigeon, run:\n\n```\ncomposer install\n```\n\nIt will download and install everything you need.\n\n### 4. Configuring\n\nPigeon has a default configuration file named `config.php`. In fact you don't have to configure anything to start using Pigeon, since it comes pre-configured and ready to use after instalation.\n\nHowever the best practice is to create a local configuration file named `config.local.php` that overrides only the directives you want to change, e.g. increase security.\n\nGo to the folder where Pigeon is and create your local configuration file:\n\n```\ncp config.php config.local.php\n```\n\nNext edit `config.local.php` with your needs, such as SMTP credentials, a prefix text for all messages, etc.\n\n***IMPORTANT: Pigeon does not use any authentication token by default, so any request will be served (and an e-mail be sent). It is highly recommended that you set a value for the `AUTH_TOKEN` directive in your `config.local.php` to password-protect your service.***\n\nIf nothing else, ensure you have `AUTH_TOKEN` not empty in your `config.local.php`, like this:\n\n```\ndefine('AUTH_TOKEN', 'mysuperhardtoguesspassword');\n```\n\nPlease check the [config.php](config.php) file for more configuration directives.\n\n## Usage\n\nAssuming your Pigeon installation is available at `http://localhost/pigeon`, you can send e-mails by sending a `POST` or `GET` request containing the fields `to`, `subject` and `text` as follows:\n\n```\ncurl -d \"to=john@snow.com\u0026subject=Notice\u0026text=Winter is coming!\" http://localhost/pigeon\n```\n\nPigeon will reply with a JSON reponse, e.g.\n\n```\n{\"success\":true,\"method\":\"send\",\"timestamp\":1508918383,\"version\":\"1.0.0\"}\n```\n\nIf you have configured the `AUTH_TOKEN` directive in your `config.local.php` file, you need to also specify a `token` param that matches your `AUTH_TOKEN` value for your request to be accepted.\n\nAssuming `AUTH_TOKEN` is `mysuperhardtoguesspassword`, your e-mail request will be:\n\n```\ncurl -d \"to=john@snow.com\u0026subject=Notice\u0026text=Winter is coming!\u0026token=mysuperhardtoguesspassword\" http://localhost/pigeon\n```\n\n## Limitations\n\nPigeon is by no means an enterprise grade microservice. It is not designed around security and there is no queue system in place, so e-mails are dispatched as they arrive. You can choke the web server by making lots of request at the same time. Requests hang the web server up for the duration of the e-mail sending process, which also consumes resources unnecessarily. Pigeon is a quick drop-in solution for small projects that just want to send e-mails, no questions asked.\n\n## License\n\nPigeon is licensed under the terms of the [MIT](https://choosealicense.com/licenses/mit/) Open Source\nlicense and is available for free.\n\n## Changelog\n\nSee all changes in the [CHANGELOG](CHANGELOG.md) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdovyski%2Fpigeon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdovyski%2Fpigeon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdovyski%2Fpigeon/lists"}