{"id":13674302,"url":"https://github.com/Feuerhamster/mailform","last_synced_at":"2025-04-28T14:31:12.806Z","repository":{"id":42184315,"uuid":"375079369","full_name":"Feuerhamster/mailform","owner":"Feuerhamster","description":"The lightweight self-hosted email service for contact forms and more!","archived":false,"fork":false,"pushed_at":"2024-03-04T19:40:12.000Z","size":90,"stargazers_count":100,"open_issues_count":2,"forks_count":9,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-03-04T21:01:31.350Z","etag":null,"topics":["api","email","email-relay","self-hosted","smtp"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Feuerhamster.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","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}},"created_at":"2021-06-08T16:41:17.000Z","updated_at":"2024-04-15T13:06:14.250Z","dependencies_parsed_at":"2024-03-04T21:08:42.747Z","dependency_job_id":null,"html_url":"https://github.com/Feuerhamster/mailform","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Feuerhamster%2Fmailform","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Feuerhamster%2Fmailform/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Feuerhamster%2Fmailform/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Feuerhamster%2Fmailform/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Feuerhamster","download_url":"https://codeload.github.com/Feuerhamster/mailform/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251330219,"owners_count":21572247,"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":["api","email","email-relay","self-hosted","smtp"],"created_at":"2024-08-02T11:00:45.549Z","updated_at":"2025-04-28T14:31:12.282Z","avatar_url":"https://github.com/Feuerhamster.png","language":"TypeScript","funding_links":[],"categories":["Software"],"sub_categories":["Communication - Email - Mail Delivery Agents"],"readme":"# 📨 MailForm\n\u003e The lightweight email service for contact forms and more!\n\nThis is basically a minimal self-hosted open source alternative to [Formspree](https://formspree.io/) and [SendGrid](https://sendgrid.com/).\n\nUnlike other mail services (that often gives you an API key for backends), this self-hosted mail service is designed to be accessed directly from a frontend, but also offers you the option to use it as a mail service with configurable API keys.\n\n### Features\n- Access via API or HTML form with redirects\n- Configurable CORS and Origin restriction\n- ReCaptcha and hCaptcha support\n- Custom rate limits for every target\n- Optional API keys\n\n### Planned features\n- [ ] Email Templates\n- [x] File Uploads for attachments\n- [x] ReCaptcha and hCaptcha support\n\n### Used frameworks \u0026 libraries\n- [Express](https://expressjs.com/)\n- [Typescript](https://www.typescriptlang.org/)\n- [Nodemailer](https://nodemailer.com/about/)\n- [Validate.js](https://validatejs.org/)\n- [rate-limiter-flexible](https://www.npmjs.com/package/rate-limiter-flexible)\n- [axios](https://github.com/axios/axios)\n\n## 💽 Installation\n### Docker\n```shell\ngit clone https://github.com/Feuerhamster/mailform.git\ncd mailform\ndocker build -t Feuerhamster/mailform .\ndocker run Feuerhamster/mailform\n  -e PORT=3000\n  -e PROXY=true\n  -v /your/custom/path /app/targets\n```\n\n### Manually\n*Requires NodeJS 14 or higher*\n\n```shell\ngit clone https://github.com/Feuerhamster/mailform.git\ncd mailform\nnpm install\nnpm run build\nnpm run start\n```\n\n## ⚙️Configuration\n### Application\nMailForm can be configured using environment variables.\n\n**Environment variables:**\n- `PORT` The port on which the application starts. If not provided, a random port will be selected.\n- `TARGETS_DIR` Path to the directory with your target files. Default is `/targets` of the project root.\n- `PROXY` A boolean that enables the \"trust proxy\" option of Express. **Enable this if you're using MailForm behind a reverse proxy like NGINX!** Default value is false.\n\n### Targets\nTargets are your different endpoints each with its own rate limits and smtp provider.\nThey are JSON files placed in the `/targets` directory. \n\n**Example target:**\n```json\n{\n    \"smtp\": \"smtps://username:password@smtp.example.com\",\n    \"origin\": \"my-website.com\",\n    \"recipients\": [\"example@example.com\"],\n    \"rateLimit\": {\n        \"timespan\": 300,\n        \"requests\": 1\n    },\n    \"captcha\": {\n        \"provider\": \"hcaptcha\",\n        \"secret\": \"xxx\"\n    }\n}\n```\n\n**Available fields:**\n- `smtp` *required* | A valid SMTP(S) url.\n- `origin` *optional* | A HTTP origin that is used for CORS and to restrict access. Default is * if not set.\n- `recipients` *required* | An array of email addresses which should receive the email.\n- `from` *optional* | The \"from\" field of an email. This is used as fallback if no \"from\" is provided in the request.\n- `subjectPrefix` *optional* | A target-wide prefix for the email subject.\n- `key` *optional* | A string used as API key if you want to restrict access to this target.\n- `redirect` *optional*:\n  - `success` *optional*: A valid relative or absolute URL to redirect the user if the mail was sent successful.\n  - `error` *optional*: A valid relative or absolute URL to redirect the user if the mail can't be sent due to an error.\n- `rateLimit` *required*:\n    - `timespan` *required* | Timespan (in seconds) for the rate limiter to reset.\n    - `requests` *required* | Allowed amount of requests in the given timespan.\n- `captcha` *optional*:\n  - `provider` *required if captcha* | The captcha provider (\"recaptcha\" or \"hcaptcha\").\n  - `secret` *required if captcha* | Secret key for your captcha.\n\nFor the exact validations of the fields please see here: [target.ts](/src/models/target.ts)\n\n## 📫 Usage\n### Fields\nWhether as formular data or json, the fields are the same.\n\n- `from` *optional* | The email address of the sender. If this filed is not set, the \"from\" field of your target will be used.\n- `firstName` *optional* | A classic first name filed which will be attached to the \"from\" field of the email.\n- `lastName` *optional* | A classic last name filed which will be attached to the \"from\" field of the email.\n- `subjectPrefix` *optional* | A Prefix for the email subject.\n- `subject` *required* | The email subject.\n- `body` *required* | The email body (supports HTML).\n  \n- `g-recaptcha-response` *only required if target use captcha* | Field for ReCaptcha response.\n- `h-captcha-response` *only required if target use captcha* | Field for hCaptcha response.\n\nFor the exact validations of the fields please see here: [posts.ts](/src/models/post.ts)\n\n**Important info:** If a redirect is configured for your target, it will always return the redirect, even if you make an API call.\nIf no redirect is set, http status codes will be returned.\n\n### Captchas\nMailForm supports both [ReCaptcha](https://www.google.com/recaptcha/) and [hCaptcha](https://www.hcaptcha.com/).\n\nTo use captchas, you have to configure it in your target.\n\nOn a request, the corresponding field (`g-recaptcha-response` for ReCaptcha or `h-captcha-response` for hCaptcha) have to be filled for validation.\nIf you use the captcha widget in a form, this will happen automatically.\nIf you use an API request, you have to fill it manually.\n\n### HTML Form\n\n**Example html form:**\n```html\n\u003cform method=\"post\" action=\"https://mailform.yourserver.com/your-target-file-name\"\u003e\n    \u003cinput type=\"email\" name=\"from\" placeholder=\"Sender's email address\"/\u003e\n    \u003cinput type=\"text\" name=\"firstName\" placeholder=\"First name\" /\u003e\n    \u003cinput type=\"text\" name=\"lastName\" placeholder=\"Last name\" /\u003e\n    \u003cinput type=\"hidden\" name=\"subjectPrefix\" value=\"[App-Question] \" /\u003e\n    \u003cinput type=\"text\" name=\"subject\" placeholder=\"Subject\" /\u003e\n    \u003cdiv class=\"g-recaptcha\" data-sitekey=\"your_site_key\"\u003e\u003c/div\u003e\n    \u003ctextarea name=\"body\" placeholder=\"Your message\"\u003e\u003c/textarea\u003e\n\u003c/form\u003e\n```\n\nTo work properly, you may want to configure a redirect in the target.\n\n### API\nSimply make a request to `/:target` (replace with your target's file name).\nIf you have set an API key, add the HTTP Authorization header with type `Bearer` and then the key.\nMake sure to also use the right origin (if not set automatically because the request is from a backend).\n\n\u003e ⚠ Since the file upload feature got added, there is an Issue with `application/json`. Please use multipart form or form urlencoded for API requests. I am working on a rewrite where this gets fixed.\n\n**Example request:** \n```http request\nPOST https://mailform.yourserver.com/your-target-file-name\nOrigin: your-configured-origin.com\nContent-Type: application/json\nAuthorization: Bearer your-optional-api-key\n\n{\n  \"from\": \"example@example.com\",\n  \"subject\": \"your subect\",\n  \"body\": \"your message\",\n}\n```\n\n**Possible status codes:**\n- `200` Email was successfully sent.\n- `401` Authentication failed: API key not present or wrong.\n- `403` Forbidden because of wrong origin header.\n- `404` Target not found.\n- `500` Sending the email failed.\n\n## 👋 Contribution\nFeel free to create issues and pull requests if you want!\n\nPlease keep up with the code style and discuss new features beforehand with the project owner.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFeuerhamster%2Fmailform","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFeuerhamster%2Fmailform","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFeuerhamster%2Fmailform/lists"}