Custom Forms

Custom Forms lets you build forms with a visual editor, collect and manage submissions inside the admin, route them to email, push them to external systems through a signed webhook, and protect them from spam — all without writing code. It works on a standard Magento store and on a headless (Astro) storefront via GraphQL or REST.

Compatibility

Magento

Open Source 2.4.9 GA (and later 2.4.x).

PHP

Tested on 8.4 and 8.5.

Storefront

Standard Luma/PWA and headless (Astro) via GraphQL/REST.

PDF (optional)

Bundled mpdf/mpdf for PDF export & PDF email attachments.

What makes this different

Unlike most form extensions, Custom Forms ships one tier (no paywalled “Pro”), works on a headless storefront out of the box, signs every webhook with HMAC-SHA256, and layers AI spam scoring and reCAPTCHA v3 on top of a honeypot and keyword filter.

Quick start

1. Go to Content → Custom Forms → Forms and click Create New Form.

2. On the General tab, enter a Form Title and a Form Code (lowercase, numbers and underscores — used for embedding).

3. Open the Form Builder tab and add your fields.

4. Set the Submit Button Text and Success Message on the Content tab.

5. Click Save Form.

6. Embed it on a page — or it’s instantly available to a headless storefront by its code.

---

Global configuration

Before building forms, set the store-wide defaults at Stores → Configuration → AgenticEcom · Sales, Customers & Marketing → Custom Forms. Every setting here is a default that individual forms can build on; spam, reCAPTCHA, email and webhook all live here. The working screens are under Content → Custom Forms (Forms, Submitted Data, Autoresponder Templates, Configuration).

General

• Enable Custom Forms — master on/off switch for the whole module.

Spam Protection

• Enable Honeypot Field — adds a hidden field that bots fill but humans never see. A filled honeypot is treated as spam. Recommended.
• Spam Score Threshold — submissions scoring above this (0.0–1.0) are marked Spam. Default 0.7.
• Auto-Reject Spam — when Yes, spam is discarded entirely instead of being stored and flagged.
• Blocked Keywords — comma-separated words; any submission containing one is flagged.
• AI Spam Scoring — when Yes, ambiguous submissions get a second opinion from Google Gemini.
• Google AI API Key — your own key from Google AI Studio. Stored encrypted, used only by this module.
• AI Model — the Gemini model used for scoring.

reCAPTCHA v3

• Site Key — public key used by the storefront widget (read automatically over GraphQL — no env vars).
• Secret Key — private key used server-side to verify submissions. Stored encrypted.
• Minimum Score — v3 returns a 0.0–1.0 score per submission; those below this are rejected. Default 0.5.

Create a reCAPTCHA v3 key pair at google.com/recaptcha/admin for your storefront domain, then enable CAPTCHA per form on its Content tab.

Admin Notification

• Enable Notification to Email — email your team on every genuine submission.
• Send Emails To — recipient address(es), comma-separated, no spaces.
• Email Sender — the store sender identity used.
• Email Template — which template builds the email.
• Attach Submission PDF — attach a PDF of each submission (requires the mpdf library).

Reply / Autoresponder

Reply Form Configuration (used when you reply from the admin):

• Email Sender, Email Template, Send Blind Copy to (comma-separated BCC).

Autoresponder (auto-thanks the submitter):

• Enable Auto Response — sends to the form’s email field, or the customer’s account email. Can be overridden per form.
• Email Sender, Auto-Reply Email Template.

Webhook / GDPR / Advanced

Webhook / Zapier:

• Enable Submission Webhook, Webhook URL (HTTPS endpoint, e.g. a Zapier Catch Hook), Signing Secret (optional HMAC key, stored encrypted).

GDPR Consent:

• Enable GDPR Consent Checkbox, Consent Text.

Advanced:

• Date Format — how dates appear in submissions/exports.
• File Upload Links Lifetime (days) — expire uploaded-file links after N days (0 = never).
• Submission Retention (days) — auto-delete submissions older than N days (0 = keep forever).

---

The forms grid

Content → Custom Forms → Forms lists every form you’ve built. Each row shows the ID, Form Name, Code, whether it’s Active, whether AI Spam Protection is on, and the Created date. Use the row’s Select → Edit / Delete, or the Actions menu for bulk operations. Create New Form (top-right) starts a new one.

A form for every job

Contact, quote requests, surveys, job applications, newsletter signups, wholesale account applications — anything you’d otherwise hard-code. Each form has its own code, fields, routing and spam settings.

Building a form

A form-edit screen has five tabs down the left under FORM CONFIGURATION: General, Notifications, Content, Form Builder and Embedding.

General — form information

• Enable Form — turn this individual form on or off.
• Form Title — shown in the grid and (optionally) above the form.
• Form Code — the unique identifier used for embedding. Lowercase letters, numbers and underscores only.
• Store Views — restrict the form to specific store views (leave to show everywhere).
• Customer Groups — restrict the form to specific customer groups.

Note

The form’s schedule, save-referer and survey behaviour (submit-once) are also controlled here — handy for time-boxed campaign forms or one-response surveys.

Content — buttons, message & display

• Submit Button Text — the call-to-action on the button (e.g. Send message, Request a Quote).
• Success Message — shown after a successful submission. Set / AJAX-style success without a page reload.
• Show as Popup — render the form inside a modal triggered by a button instead of inline.
• Popup Button Text — the label of that trigger button.
• Enable CAPTCHA — turn on reCAPTCHA v3 verification for this form (needs keys in global config).

Notifications — per-form email routing

• Send Email to Admin on Submission — toggle admin notifications for this form.
• Notification Recipients — per-form recipients (comma-separated, no spaces). Overrides the global default.
• Email Template — leave on Use Default, or pick a custom one. You can manage reusable form-email templates in the module’s own Content → Custom Forms → Autoresponder Templates screen (or use a core Magento template from Marketing → Email Templates).
• Send Auto-Reply to Submitter — per-form autoresponder. Requires an email field in the form so the module knows where to reply.

Form Builder — drag & drop

The builder has a Form Layout canvas on the left and a Field Types palette on the right. Click a palette field to append it, or drag it onto the canvas. Every field has a drag handle to reorder, plus Duplicate, Edit and Delete actions.

Field types

Input

• Text Input — short text (names, references).
• Email — validated email address (used by the autoresponder).
• Number — numeric-only input.
• Phone — telephone number.
• URL — validated web address.
• Password — masked input.
• Text Area — long text (messages, descriptions, reviews).
• Address Block — a ready-made group: address lines, city, county, postcode, country.

Selection

• Dropdown — single choice from a list.
• Date Picker · Time Picker · Date & Time — calendar/clock inputs.
• File Upload — attach a file (see File uploads).
• Country — country selector.
• Colour Picker · Range Slider — visual value pickers.

Multi-choice

• Checkboxes — multiple selections.
• Toggle Switch — a single on/off.
• Radio Buttons — one of several.
• Multi-Select — multiple from a list.
• Opinion Scale — a 1–N rating with end labels (great for surveys/NPS).

Layout & advanced

• Heading & Paragraph — rich-text blocks (see Rich text).
• Divider · Spacer — visual structure.
• Page Break — split a long form into multiple pages.
• Hidden Field — pass a fixed value through with the submission.
• Star Rating — a 1–5 star input.

Field settings

Click the Edit (pencil) on a field to configure it:

• Field Label — shown above the field.
• Field Name — the data key (lowercase, no spaces). This is the key you’ll see in submissions and the API payload.
• Placeholder — hint text inside the input.
• Required — make the field mandatory (enforced in the browser and server-side).
• CSS Class — a custom class for styling.
• Validation — None, Email, URL, Alphanumeric or Numeric (also enforced server-side).
• Column Width — 100 / 75 / 66 / 50 / 33 / 25%. Fields whose widths add up to 100% sit side by side on one row, and stack on mobile.
• Conditional Logic — show or hide the field when other fields match rules (AND/OR).

Rich text (Heading & Paragraph)

Heading and Paragraph fields carry a full WYSIWYG editor in their Content setting. Format with the toolbar, or click <> Source code to paste/edit raw HTML. Whatever you enter renders formatted on the storefront — type plain text and it’s wrapped for you; paste HTML and it’s sanitised and rendered.

File uploads

A File Upload field accepts these types by default, up to 5 MB each:

jpg, jpeg, png, gif, webp, bmp, heic · pdf, doc, docx, xls, xlsx, ppt, pptx · txt, csv, rtf, odt, ods, zip

Uploads are stored safely

Executable and script types (.php, .html, .svg, .exe, …) are rejected. On a headless storefront the file is sent inline as base64, then the server extracts it to media/customforms/uploads/YYYY/MM/, validates the type and size, and stores a URL — never a raw blob in the database. Links can be set to expire (Advanced → File Upload Links Lifetime).

Saving options

Save Form returns to the list · Save and Continue Edit stays on the form (needed before the embed codes resolve) · Save & Duplicate saves, then opens a fresh copy with a new unique code.

Embedding a form

After the first save, the form’s Embedding tab shows three ready-to-paste snippets:

CMS block / page

<div class="agentic-custom-form agentic-form--contact_us"></div>

Paste into any CMS block or page (Show/Hide Editor → HTML). The storefront renders the live form in its place.

Astro component

<CustomForm code="contact_us" client:visible />

Drop this tag into any Astro page/component to render the form.

Direct URL

/forms/contact_us

A standalone link to the form for sharing directly.

---

Submissions

Open Content → Custom Forms → Submitted Data.

• The grid lists every submission with Status (New, Read, Replied, Spam), Spam Score, email, name, IP and date — filter, search and sort.
• Select → View opens the full submission with every field value (uploaded files appear as download links) and an inline reply form. Opening a New submission marks it Read.
• Reply emails the submitter (using your Reply Form template) and marks it Replied.
• Actions (mass): set status, mark as spam, or delete in bulk.
• Export to CSV — a spreadsheet of all submissions (UTF-8, Excel-friendly).
• Export to PDF — a branded PDF (uses the bundled mpdf library). Per-form export buttons live on the form-edit action bar.

How a submission is processed

One server pipeline handles both the standard storefront and the headless GraphQL/REST endpoints, so validation, spam scoring and notifications behave identically everywhere.

Email notifications

• Admin Notification — email your team on every genuine submission. Recipients, sender and template are set globally and can be overridden per form; optionally attach a PDF.
• Autoresponder — automatically thank the submitter; sends to the form’s email field.
• Reply Form — the template, sender and BCC used when you reply from the admin.

Custom values in notification emails

You can pull any field’s value into your email templates. In a template (an Autoresponder Template under Content → Custom Forms → Autoresponder Templates, or a core AgenticEcom Custom Form template under Marketing → Email Templates), reference a field by its Field Name — for example a field named order_ref:

Reference supplied: {{var data.order_ref}}

Every submitted field is available on the data object by its field name, so admin and autoresponder emails can be fully personalised.

Spam protection

1. Honeypot — a hidden field bots fill but humans don’t; a filled honeypot is treated as spam.

2. Blocked keywords — comma-separated words that flag a submission.

3. Heuristics — built-in checks (excess links, known spam phrases, all-caps, mixed scripts).

4. AI scoring (Google Gemini) — an optional second opinion for ambiguous submissions, using your own Google AI key.

5. reCAPTCHA v3 — set your keys, enable CAPTCHA on a form, and submissions are verified server-side.

Fail closed

reCAPTCHA verification fails closed: a missing, forged or low-score token is rejected. Submissions at/above the spam threshold (default 0.7) are marked Spam and skip all notifications; you can optionally auto-reject them entirely.

Webhook / Zapier

Push every new submission as JSON to an external URL (Zapier, Make, n8n, a CRM, or your own endpoint). Enable it, set the URL, and optionally a signing secret.

Signed & verifiable

When a secret is set, each request carries an HMAC-SHA256 signature header X-AgenticEcom-Signature: sha256=<hex>, so the receiver can verify the payload came from your store and wasn’t tampered with. Delivery is best-effort and never blocks a submission.

GDPR & advanced

• GDPR Consent — add a consent checkbox with custom text.
• Date Format — how dates appear in submissions/exports.
• File Upload Links Lifetime — expire uploaded-file links after N days (0 = never).
• Submission Retention — auto-delete submissions older than N days (0 = keep forever).

Headless / API

For a decoupled (Astro) storefront, forms are delivered and submitted over GraphQL (a REST equivalent is also available).

GraphQL

# Fetch a form definition
{ customForm(code: "contact_us") {
    form_id name code is_active enable_captcha
    submit_button_text success_message recaptcha_site_key fields_json
} }

# Submit a form
mutation {
  submitCustomForm(
    form_code: "contact_us"
    data: "{\"name\":\"Jane\",\"email\":\"jane@example.com\",\"message\":\"Hello\"}"
    recaptcha_token: "<v3 token, when CAPTCHA is enabled>"
  ) { success message submission_id }
}

REST

GET  /V1/customforms/form/{code}     → form definition
POST /V1/customforms/submit          → { formCode, data, customerEmail?, refererUrl? }

The submit path runs server-side validation, spam scoring and reCAPTCHA, stores the submission, and triggers the admin email, autoresponder and webhook — identically for GraphQL and REST.

Optional packages

These add functionality but aren’t required to run the module:

• mpdf/mpdf — enables Export to PDF and Attach Submission PDF on notification emails.

FAQ

Do I need a developer to add a form to a page?

No. Copy the CMS block code from the Embedding tab and paste it into any CMS page or block (in HTML mode). On a headless storefront, drop the <CustomForm code="…" /> tag onto an Astro page.

How does the autoresponder know who to reply to?

It reads the form’s email field. Add an Email field to the form (and enable the autoresponder globally or per-form) and replies go to whatever the submitter entered.

Is the form secure against bots and spam?

Yes — five layers: a honeypot, a blocked-keyword list, built-in heuristics, optional AI scoring, and reCAPTCHA v3 (which fails closed). Submissions over the spam threshold are flagged and skip all notifications, or can be auto-rejected.

What about secure development practices?

All input is validated and spam-scored server-side (never trusting the browser); uploaded files are restricted to a safe-type allowlist with a size cap and stored outside the database; secret keys (reCAPTCHA, AI, webhook) are stored encrypted; and the webhook payload is HMAC-signed. The module is verified clean on PHP 8.4 and 8.5.

Can I personalise the notification emails?

Yes. Any field value is available in the email template as {{var data.<field_name>}} — see Custom values in notification emails.

Configuration reference

Stores → Configuration → AgenticEcom · Sales, Customers & Marketing → Custom Forms

Group	Key settings
General	Enable Custom Forms
Spam Protection	Honeypot, score threshold, auto-reject, blocked keywords, AI scoring + Google AI key + model
Google reCAPTCHA v3	Site key, secret key, minimum score
Admin Notification	Enable, recipients, sender, template, attach PDF
Reply Form Configuration	Sender, template, BCC
Autoresponder	Enable, sender, template
Webhook / Zapier	Enable, URL, signing secret
GDPR Consent	Enable, consent text
Advanced	Date format, file-link lifetime, submission retention