{"id":13559123,"url":"https://github.com/Taisiias/formmailer","last_synced_at":"2025-04-03T14:31:18.363Z","repository":{"id":17602325,"uuid":"82327436","full_name":"Taisiias/formmailer","owner":"Taisiias","description":"HTTP server that emails data submitted on static website forms.","archived":false,"fork":false,"pushed_at":"2022-12-07T17:29:43.000Z","size":2765,"stargazers_count":4,"open_issues_count":21,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-15T07:27:30.647Z","etag":null,"topics":["forms","http","nodejs","smtp","static-site"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/Taisiias.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-17T18:44:38.000Z","updated_at":"2023-01-17T00:58:57.000Z","dependencies_parsed_at":"2023-01-11T20:26:55.898Z","dependency_job_id":null,"html_url":"https://github.com/Taisiias/formmailer","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/Taisiias%2Fformmailer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Taisiias%2Fformmailer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Taisiias%2Fformmailer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Taisiias%2Fformmailer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Taisiias","download_url":"https://codeload.github.com/Taisiias/formmailer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247018426,"owners_count":20870002,"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":["forms","http","nodejs","smtp","static-site"],"created_at":"2024-08-01T12:05:21.811Z","updated_at":"2025-04-03T14:31:18.055Z","avatar_url":"https://github.com/Taisiias.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","nodejs"],"sub_categories":[],"readme":"# FormMailer\n\n![CircleCI badge](https://img.shields.io/circleci/project/github/Taisiias/formmailer.svg)\n[![NPM version][npm-image]][npm-url]\n\n**FormMailer is a simple way to receive emails from contact forms on your static website.**\n\nIt runs as a service and emails contents of the forms posted to it.\n\n![Workflow](/img/formmailer-workflow.png)\n\nSuppose you have this HTML in your static page:\n\n```html\n\u003chtml\u003e\n\u003cbody\u003e\n    \u003cform action=\"http://myformmailer.mydomain.com/submit\" method=\"post\"\u003e\n        \u003cdiv\u003e\n            \u003clabel for=\"msg\"\u003eMessage:\u003c/label\u003e\n            \u003ctextarea id=\"msg\" name=\"User Message\"\u003e\u003c/textarea\u003e\n        \u003c/div\u003e\n        \u003cdiv class=\"button\"\u003e\n            \u003cbutton type=\"submit\"\u003eSend your message\u003c/button\u003e\n        \u003c/div\u003e\n    \u003c/form\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\nFormMailer service deployed on your domain `http://myformmailer.mydomain.com/` will receive user-submitted POST requests and send emails similar to this one:\n\n```\n\u003e Content-Type: text/plain\n\u003e From: formmailer@mydomain.com\n\u003e To: support@mydomain.com\n\u003e Subject: Form submitted on http://mydomain.com/index.html\n\u003e Message-ID:\n\u003e  \u003cdfc9cdf6-ec60-1a6a-089c-bed4566b05ef@mydomain.com\u003e\n\u003e Content-Transfer-Encoding: 7bit\n\u003e Date: Mon, 14 Aug 2017 13:29:25 +0000\n\u003e MIME-Version: 1.0\n\u003e\n\u003e Submitted user form was received by FormMailer server, see details below.\n\u003e\n\u003e Referrer page: http://mydomain.com/index.html\n\u003e\n\u003e User Message:\n\u003e   Hello world!\n\u003e\n\u003e Submitter IP address: 1.2.3.4\n```\n\nFormMailer also:\n\n* supports HTTPS.\n* supports plain text and HTML emails.\n* uses [Mustache.JS](https://github.com/janl/mustache.js) templates for email body and subject.\n* saves all received data (and sent emails) to the local SQLite database.\n* understands reCAPTCHA.\n* supports `application/json` and `application/x-www-form-urlencoded` content types.\n\n## Running\n\n1. Install [Node.js](https://nodejs.org/en/) (version 8 or higher).\n\n2. Install FormMailer with the command:\n\n    ```bash\n    npm install -g formmailer\n    ```\n\n3. Create a new `config.json` file and place following defaults inside:\n\n    ```json\n    {\n        \"recipientEmails\" : \"you@yourdomain.com\",\n        \"fromEmail\": \"formmailer@localhost\"\n    }\n    ```\n\n     Edit settings specific for your environment (see [Configuration options](#configuration-options)).\n\n4. Start FormMailer:\n\n    ```bash\n    formmailer\n    ```\n\n    You can specify `config.json` file location with `-c` command line argument: `formmailer -c /path/to/my/config.json`.\n\nNow, change the action field in your HTML form(s) to something like this:\n```html\n\u003cform method=\"post\" action=\"http://[domain or ip]:[port]/submit\"\u003e ...\n```\n\nHere `[domain or ip]` should be your FormMailer server domain (or IP address), and `[port]` should be the port which your FormMailer instance listens to (`httpListenPort` config setting).\n\n## Configuration options\n\nDefault configuration file location is `./config.json`. You can provide different location with `-c` command line argument.\n\nOption  | Description | Default\n--------|-------------|--------\n`recipientEmails` | E-mail recipient address. String or array of strings (for multiple recepients). | Required field.\n`fromEmail` | E-mail address that will be provided in `From:` email header. | `\"formmailer@localhost\"`\n`smtpOptions` | [Nodemailer options](https://nodemailer.com/smtp/) object. | `{host: \"localhost\", port: 25, tls: { rejectUnauthorized: false }}`\n`enableHtmlEmail` | Enables sending out HTML versions of emails. | `true`\n`enableHttp` | Determines if HTTP should be enabled | `true`\n`httpListenIP` | IP address to listen HTTP requests from. | `\"0.0.0.0\"` (all IP addresses)\n`httpListenPort` | Port to listen HTTP requests from. | `80`\n`enableHttps` | Determines if HTTPS should be enabled | `true`\n`httpsListenIP` | IP address to listen HTTPS requests from. | `\"0.0.0.0\"` (all IP addresses)\n`httpsListenPort` | Port to listen HTTPS requests from. | `443`\n`httpsPrivateKeyPath` | Path to HTTPS private key. Specify to enable HTTPS. | `\"\"`\n`httpsCertificatePath` | Path to HTTPS certificate. Specify to enable HTTPS. | `\"\"`\n`enableRecaptcha` | If false, receiver handler should not check `g-recaptcha-response` field even if site key is provided. | `false`\n`reCaptchaSecret` | Site secret reCAPTCHA key. No captcha checks will be performed if this value is not set. | `\"\"`\n`reCaptchaSiteKey` | Public reCaptcha site key. | `\"\"`\n`formTargets` | See details in [Sending different forms to different recipients](#sending-different-forms-to-different-recipients)| { }\n`redirectFieldName` | Name of the HTML input that contains redirect URL address. | `\"_redirect\"`\n`subject` | Email subject field content. Special entry `{{{referrerUrl}}}` will be changed to the address of the webpage from where the form is submitted. | `\"Form submitted on {{{referrerUrl}}}\"`\n`logLevel` | How detailed logging should be (`error`, `warn`, `info`, `verbose`, `debug`, `silly`). | `\"info\"`\n`enableWebInterface` | Enables separate HTTP server that provides the UI for viewing sent email history. | `true`\n`webInterfaceIP` | Sent email history HTTP server IP address binding. | `\"0.0.0.0\"` (all IP addresses)\n`webInterfacePort` | Sent email history HTTP server port. | `3002`\n`assetsFolder` | Path to the folder containing static assets. | `\"./assets\"`\n`databaseFileName` | Path to the SQLite database file. | `\"./formmailer.db\"`\n`maxHttpRequestSize` | Maximum allowed size of HTTP requests, in bytes. | `1000000`\n\n## Optional features\n\n### Special fields\n\nHTML fields with names that start with the underscore character are ignored by FormMailer:\n\n```html\n\u003cinput type=\"text\" name=\"_thisIsIgnored\" value=\"stuff that doesn't have to be sent in email\"\u003e\n```\n\nAlso, there are some special fields that can be provided in hidden inputs:\n\nInput name | Meaning\n-----------|--------\n`_redirect` | URL where to redirect user after the form is successfuly submitted. If `_redirect` field is omitted, user will be redirected to the default `thanks.html` page hosted by FormMailer.\n`_formurl` | Value will replace referrer in emails.\n`_formname` | Value will show up in email header. Should help to identify which form was submitted if there are several on the page.\n\n### reCAPTCHA\n\nTo enable reCAPTCHA checking:\n\n1. Sign up for reCAPTCHA (https://www.google.com/recaptcha/admin), get public site key and secret key.\n\n3. Provide public site key value into `reCaptchaSiteKey` option in your config file.\n\n3. Provide secret key value into `reCaptchaSecret` option in your config file.\n\nThere is no need to make any modifications in your site form, reCAPTCHA will be checked on the intermediate page generated by FormMailer.\n\nTo disable reCAPTCHA checking, set `enableRecaptcha` to `false`.\n\nIf no `reCaptchaSiteKey` is provided in config, you have to integrate reCAPCHA on your site manually, see below.\n\n#### Manual reCAPTCHA\n\nIf you are processing reCAPTCHA manually on your site, you need to provide to FormMailer `g-recaptcha-response` field in your POST request (either `x-www-form-urlencoded` or `json`).\n\nRefer to the link below for reCAPTCHA documentation:\n\nhttps://developers.google.com/recaptcha/docs/display\n\n### Sending different forms to different recipients\n\nFirst, add a dictionary similar to the one below to the configuration file:\n\n```json\n\"formTargets\": {\n    \"contact\": \"contact@mydomain.com\",\n    \"support\": [\"support@mydomain.com\", \"team@mydomain.com\"],\n    \"sales\": {\n        \"recipient\": \"sales@mydomain.com\",\n        \"subject\": \"Purchase inquiry submitted\"\n    }\n}\n```\nAfter that, provide form's action URL in the following format\n\n`http://formmailer.domain.com/submit/\u003cformtarget\u003e` where `\u003cformtarget\u003e` is a key in this dictionary.\n\n```html\n\u003cform method=\"POST\" action=\"http://formmailer.domain.com/submit/sales\"\u003e...\n```\n\nFormMailer will use a corresponding recipient (and optionally a subject) instead of the default one.\n\n### Enabling HTTPS\n\nAcquire SSL certificate (either buy from one of the authorities or [get one for free](https://gethttpsforfree.com/)). You should have two files (usually `.pem` and `.crt`). Put them in some directory.\n\nIn the configuration file add private key (`.pem`) path into `httpsPrivateKeyPath` and certificate (`.crt`) path into `httpsCertificatePath`. For example:\n\n```json\n{\n    ...\n    \"httpsPrivateKeyPath\": \"./mycert/mydomain.pem\",\n    \"httpsCertificatePath\": \"./mycert/mydomain.crt\"\n}\n```\n\nRestart FormMailer and it should automatically run HTTPS server (on port 443), along with HTTP. If you wish to disable HTTP, change `enableHttp` config setting to `false`.\n\n### JSON Resquests\n\nFormMailer accepts JSON requests, distingushing them by `content-type: application/json` HTTP header. FormMailer expects JSON to contain an object. Properties of this object along with their values will be listed in the email. Other behaviour is similar to requests with `content-type: application/x-www-form-urlencoded`, i. e. special fields with names starting with `_` will be ignored and `g-recaptcha-response` field will be used for reCAPTCHA authentication.\n\nIf email was sent successfully, JSON response `{ result: \"ok\" }` will be returned. Or `{ result: \"error\", description: \"error details description\" }`, in case of an error.\n\n### Email Templates\n\nFormMailer is using [Mustache.JS](https://github.com/janl/mustache.js) templates for email body and subject. Email can be sent both as plain text and as HTML. Sending out HTML emails can be turned off by setting `enableHtmlEmail` to `false` in the config.\n\nPath to plain text email template is `./assets/plain-text-email-template.mst`.\n\nPath to HTML template is `./assets/html-email-template.html`.\n\nSubject text template can be changed in the `subject` configuration setting.\n\nAll templates may include following variables:\n\nVariable | Description\n--------|-------------\n`formName` | Name of the form (provided by `_formname` special form field).\n`incomingIp` | Sender IP address.\n`mustacheTemplateData` | User-submitted data (key: `key`, value: `textValue`).\n`refererUrl` | Referer URL (from HTTP request headers).\n\n## Viewing Sent Emails History\n\nBy default, you can access sent emails history table by the address: `http://localhost:3002/view`. You can disable this by changing `enableWebInterface` setting to `false`.\n\n*NOTE: As there is currently no authentication in the Formmailer web-interface, it is recommended to make `webInterfacePort` (3002 by default) accessible only from local intranet. Or restrict the IP network for web-interface HTTP server by setting `webInterfaceIP` config to something different from `0.0.0.0`.*\n\n## Deploying\n\n**Example for Ubuntu 17.04**\n\nCreate a new file `/lib/systemd/system/formmailer.service` and place the following contents inside:\n\n```ini\n[Unit]\nDescription=FormMailer Service\nAfter=network.target\n\n[Service]\nType=simple\nUser=formmailer\nGroup=formmailer\nExecStart=/usr/bin/node ./dist/src/index.js -c ./config.json\nRestart=on-failure\nEnvironment=NODE_ENV=production\nWorkingDirectory=/var/formmailer\n\n[Install]\nWantedBy=multi-user.target\n```\n\nChange `WorkingDirectory` to the directory where you have cloned FormMailer.\n\nSupposing you have cloned the FormMailer repository to `/var/formmailer`, run:\n\n```bash\n$ # create user and group\n$ sudo groupadd formmailer \u0026\u0026 sudo useradd formmailer -g formmailer\n\n$ # go to the formmailer repo directory\n$ cd /var/formmailer\n\n$ # change the owner of the formmailer directory to the formmailer user\n$ sudo chown formmailer:formmailer . -R\n\n$ # force systemd to load the new service file\n$ sudo systemctl daemon-reload\n\n$ # start the service\n$ sudo systemctl start formmailer\n```\n\nDon't forget to check your firewall settings to allow outside TCP connections to the port specified in `httpListenPort` setting.\n\n*NOTE: FormMailer uses default NodeJS HTTP server. For production environment it is recommended to set up a reverse proxy (Nginx or alternative) that will hide the FormMailer service from the outside world.*\n\n## Alternatives\n\n* [Formspree](https://github.com/formspree/formspree)\n* [FormMailerService](https://github.com/abbr/FormMailerService)\n\n## License\n\n[MIT License](LICENSE)\n\n[npm-url]: https://www.npmjs.com/package/formmailer\n[npm-image]: https://img.shields.io/npm/v/formmailer.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTaisiias%2Fformmailer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTaisiias%2Fformmailer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTaisiias%2Fformmailer/lists"}