Frappe Contact Form

bench get-app https://github.com/Alex-Yablonsky/frappe-contact-form

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=Alex-Yablonsky%2Ffrappe-contact-form)](https://frappegems.com/gems/apps/Alex-Yablonsky/frappe-contact-form)

# Frappe Contact Form App **Frappe Contact Form App** is a lightweight, SMTP-only contact form app for Frappe Framework. It provides an embeddable public contact form that sends messages by email through Frappe’s outgoing email system, without creating CRM Leads, Web Form Submissions, Communications, or storing message bodies in the database by default. Current release: **v1.0.2** Developed and maintained by [Yablonsky.io](https://yablonsky.io/). --- ## Why this app exists Frappe has powerful Web Forms and CRM forms, but they are often too heavy for a simple public contact form. For many websites, a contact form should only do one thing: > accept a message, validate it, protect it from spam, and send it to a configured email inbox. This app solves that problem by separating a simple contact form from CRM workflows. Use it when you need: - a public contact form for a Frappe website; - SMTP-only message delivery; - no CRM Lead creation by default; - no Web Form Submission storage by default; - Cloudflare Turnstile support; - Google reCAPTCHA v2 support; - Google reCAPTCHA v3 support; - rate limiting and honeypot protection; - a reusable embeddable form that can be styled by each website. --- ## Main features ### SMTP-only contact form Messages are sent through Frappe’s configured outgoing email system using `frappe.sendmail()`. The recipient email is configured server-side in **Frappe Contact Form Settings** and is never accepted from the frontend request. ### No CRM submissions by default The app does not create: - CRM Lead - Web Form Submission - Communication - Contact - Address - custom message database records This makes it suitable for administrative, legal, partnership, media, advertising, and general contact pages where creating sales leads is not desired. ### CAPTCHA provider selection The app supports one selected CAPTCHA provider at a time: - `None` - `Cloudflare Turnstile` - `Google reCAPTCHA v2` - `Google reCAPTCHA v3` The selected provider is configured in **Frappe Contact Form Settings**. Only the selected frontend script is loaded. If CAPTCHA Provider is `None`, no Cloudflare or Google CAPTCHA script is loaded. ### Anti-spam protection The app includes: - honeypot field; - minimum submit time; - rate limit by IP; - rate limit by email; - optional CAPTCHA validation; - origin allow-list; - required consent checkbox. ### Frappe session compatibility The embedded frontend supports guest users and logged-in Frappe users. For logged-in sessions, the app automatically attaches the CSRF token to the submit request. ### Clean styling model The app ships with neutral product CSS. For project-specific styling, use: ```html data-fcf-no-css="1" ``` on the embed container and style the `.fcf-*` classes in your site, theme, or page CSS. This keeps the app reusable across different Frappe websites. --- ## Compatibility ### Tested with - Frappe Framework: `16.18.3` - Frappe CRM: `1.72.0` - Frappe Builder: `1.24.7` - Ubuntu: `24.04` - Bench production setup with Supervisor and Nginx - Outgoing Email Account configured in Frappe ### Expected compatibility - Frappe Framework `v16.x` - ERPNext `v16.x` environments, because the app depends on Frappe Framework and does not require ERPNext-specific DocTypes. ### Not required ERPNext is not required. The app can be installed on a Frappe site without ERPNext. ### Not tested - Frappe Framework v15 - Frappe Framework v14 - Frappe Cloud custom app deployment - multi-tenant shared-hosting setups outside standard Bench --- ## Requirements - Frappe Bench - Frappe Framework v16 site - Working outgoing email configuration in Frappe - Optional Cloudflare Turnstile keys - Optional Google reCAPTCHA v2 or v3 keys --- ## Installation From your bench directory: ```bash cd /path/to/frappe-bench bench get-app frappe_contact_form https://github.com/Alex-Yablonsky/frappe-contact-form bench --site your-site.example.com install-app frappe_contact_form bench --site your-site.example.com migrate bench build --app frappe_contact_form bench --site your-site.example.com clear-cache bench --site your-site.example.com clear-website-cache ``` For production setups, restart the web workers if needed: ```bash sudo supervisorctl restart your-bench-name-web: ``` Replace: - `Alex-Yablonsky` with your GitHub organization or username; - `your-site.example.com` with your Frappe site name; - `your-bench-name-web` with your Supervisor group name. --- ## Configuration Open Desk and search for: ```text Frappe Contact Form Settings ``` Configure the following fields. ### General | Field | Description | |---|---| | Enabled | Turns the public form on or off. | | Recipient Email | Server-side recipient. Public requests cannot override it. | | Sender Email Account | Optional sender email/account. Leave empty to use Frappe default outgoing email. | | Default Subject Prefix | Prefix added to email subject, for example `[Contact Form]`. | | Success Message | Public success message shown after successful submit. | | Public Error Message | Generic public error message. | ### CAPTCHA | Field | Description | |---|---| | CAPTCHA Provider | `None`, `Cloudflare Turnstile`, `Google reCAPTCHA v2`, or `Google reCAPTCHA v3`. | | Turnstile Site Key | Public Cloudflare Turnstile key. | | Turnstile Secret Key | Private Cloudflare Turnstile secret key. | | Google reCAPTCHA Site Key | Public Google reCAPTCHA key. | | Google reCAPTCHA Secret Key | Private Google reCAPTCHA secret key. | | Google reCAPTCHA v3 Minimum Score | Minimum accepted v3 score. Default: `0.5`. | | Google reCAPTCHA v3 Action | Expected v3 action name. Default: `contact_form`. | ### Anti-spam | Field | Description | |---|---| | Honeypot Enabled | Enables hidden trap field for bots. | | Rate Limit Enabled | Enables rate limit checks. | | Rate Limit per IP per Hour | Default: `5` or your preferred value. | | Rate Limit per Email per Hour | Default: `3` or your preferred value. | | Minimum Submit Time Seconds | Blocks unrealistically fast submissions. | | Max Subject Length | Default: `160`. | | Max Message Length | Default: `5000`. | | Allowed Origins | Optional allow-list, one origin per line. | ### Privacy | Field | Description | |---|---| | Store Submissions | Reserved for future use. Default should remain off. | | Consent Required | Requires consent checkbox before submit. | | Consent Label | Public consent text. | ### Debug | Field | Description | |---|---| | Debug Mode | Shows more specific public errors during testing. Turn off in production. | --- ## Getting CAPTCHA keys ### Cloudflare Turnstile Create a Turnstile widget in Cloudflare and copy: - Site Key - Secret Key Use these in **Frappe Contact Form Settings**. Cloudflare Turnstile can be used without routing the website through Cloudflare. The widget still needs its own sitekey and secret key pair. ### Google reCAPTCHA v2 or v3 Create website keys in Google reCAPTCHA / Google Cloud reCAPTCHA and copy: - Site Key - Secret Key Then select either: - `Google reCAPTCHA v2` - `Google reCAPTCHA v3` For v3, also configure: - Minimum Score - Action Default action: ```text contact_form ``` --- ## Embedding the form Add this HTML to a Frappe website page, Builder page, Web Template, or custom page: ```html ``` ### Custom labels example ```html ``` ### Disable product CSS and use page/theme CSS ```html ``` When `data-fcf-no-css="1"` is used, the app does not load its own CSS. You can style the form through your site or page CSS. --- ## Frontend data attributes | Attribute | Description | |---|---| | `data-frappe-contact-form` | Form slug. Example: `main`. | | `data-fcf-locale` | Currently supports `en` and `lt`. | | `data-fcf-no-css` | Set to `1` to disable app CSS. | | `data-fcf-hide-phone` | Set to `1` to hide phone field. | | `data-fcf-hide-subject` | Set to `1` to hide subject field. | | `data-fcf-subject` | Default subject when subject field is hidden. | | `data-fcf-button-label` | Custom submit button label. | | `data-fcf-label-name` | Custom name label. | | `data-fcf-label-email` | Custom email label. | | `data-fcf-label-phone` | Custom phone label. | | `data-fcf-label-subject` | Custom subject label. | | `data-fcf-label-message` | Custom message label. | | `data-fcf-consent-label` | Custom consent label. | --- ## API endpoints ### Public settings ```text GET /api/method/frappe_contact_form.api.get_public_settings ``` Returns public configuration for the embed script. Secrets are never returned. ### Submit ```text POST /api/method/frappe_contact_form.api.submit ``` Expected JSON payload: ```json { "name": "John Smith", "email": "john@example.com", "phone": "+37060000000", "subject": "General question", "message": "Hello.", "form_slug": "main", "started_at": "1780600000.00", "consent": "1", "honeypot": "", "website": "", "captcha_token": "", "captcha_action": "" } ``` --- ## Security model The app is intentionally conservative. ### Server-side recipient The recipient email is configured in Settings and never accepted from the frontend request. ### CAPTCHA validation CAPTCHA tokens are verified server-side. ### Rate limiting Rate limits are stored through Frappe cache / Redis. ### Honeypot A hidden field helps block simple bots. ### Consent Consent can be required before submit. ### No CRM side effects The app does not create CRM Lead, Web Form Submission, or Communication records. ### No message storage by default Messages are not stored as database records by default. --- ## Email delivery The app uses Frappe’s outgoing email configuration. Before using this app in production, verify that your site can send email: - Outgoing Email Account is configured. - DKIM/SPF/DMARC are configured for the sender domain. - Email Queue is processing messages. To inspect recent queue items: ```bash bench --site your-site.example.com execute frappe.client.get_list \ --kwargs "{'doctype':'Email Queue','fields':['name','status','sender','creation','modified'],'order_by':'creation desc','limit_page_length':5}" ``` --- ## Development Run syntax checks: ```bash python3 -m py_compile \ frappe_contact_form/api.py \ frappe_contact_form/captcha.py \ frappe_contact_form/emailer.py \ frappe_contact_form/rate_limit.py \ frappe_contact_form/frappe_contact_form/doctype/frappe_contact_form_settings/frappe_contact_form_settings.py ``` Build assets: ```bash bench build --app frappe_contact_form ``` Run migration after DocType changes: ```bash bench --site your-site.example.com migrate ``` --- ## Release notes ### v1.0.0 Initial stable release. Includes: - SMTP-only public contact form; - Frappe Contact Form Settings; - public embed script; - neutral CSS; - Cloudflare Turnstile support; - Google reCAPTCHA v2 support; - Google reCAPTCHA v3 support; - server-side CAPTCHA verification; - CSRF support for logged-in Frappe sessions; - honeypot; - rate limiting; - consent checkbox; - no CRM Lead creation by default; - no Web Form Submission storage by default. --- --- ## Author Developed and maintained by [Yablonsky.io](https://yablonsky.io/). For business, automation, AI, SEO and Frappe-related projects, visit [Yablonsky.io](https://yablonsky.io/). ## License MIT