Custom Forms

VIDEO WALKTHROUGH

Custom Forms: setup guide

2:36

Recorded on version 1.0.2 · Narrated walkthrough · English captions

Jump to a chapter 8 chapters

1. 0:00Set up Custom Forms
2. 0:12Open settings and choose scope
3. 0:32Enable the form tools
4. 0:48Choose spam protection
5. 1:12Configure notification delivery
6. 1:32Build a reviewable form
7. 1:52Save and verify your setup
8. 2:14Your setup checklist

Read the full video transcript

Custom Forms 1.0.2 — Magento Admin setup

00:00:00 — Set up Custom Forms
Welcome to the Agentic Ecom Custom Forms Admin guide. We'll walk through the main setup screens and the checks to make before using the module. This guide assumes the extension is already installed.

00:00:12 — Open settings and choose scope
Start in Magento Admin and open Stores, Configuration. Choose Custom Forms. Check the Scope selector before editing. Use the appropriate website or store view where the setting supports it. The screen values here are a demonstration; enter the settings and service details that belong to your own store.

00:00:32 — Enable the form tools
Enable Custom Forms in General. Global configuration sets defaults, while the working screens are under Content, Custom Forms. Plan the fields you actually need and the destination for submissions before creating a public form.

00:00:48 — Choose spam protection
Review the honeypot, score threshold, blocked keywords and automatic rejection. Start by reviewing flagged submissions before enabling aggressive rejection. Optional AI scoring uses your own OpenAI or Google Gemini account, can incur separate charges, and can send parts of submitted text to the chosen provider. Review your privacy notice first.

00:01:12 — Configure notification delivery
Set the Admin Notification sender, recipients and template deliberately. Review the separate autoresponder and webhook groups only if you need them. A webhook forwards submission data to another system, so check its destination and signing settings. Test email transport before relying on notifications.

00:01:32 — Build a reviewable form
Open Forms and create a new form. Enter a Form Title and a stable Form Code, add the fields in Form Builder, then set the submit button and success message on Content. Save the form and embed it using the documented method. Submit a disposable test and confirm the saved data and intended notifications.

00:01:52 — Save and verify your setup
When your required settings are complete, use the screen's Save control and wait for Magento's confirmation. Then reopen the record or configuration and check the saved values at the intended scope. If the storefront still shows earlier settings, refresh the relevant caches. Test your own configuration before using it with customers.

00:02:14 — Your setup checklist
That's the Admin setup walkthrough for Custom Forms. Check permissions and scope, review the module-specific settings, then save and verify a small staging example. Use the written guide at user guides dot Agentic Ecom dot net for installation details, complete field references and any separate storefront integration steps.

Download videoEnglish captionsDownload transcript

Custom Forms 1.0.2 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 an optional 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. Optional AI spam scoring supports OpenAI and Google Gemini and is off by default. The selected external provider may charge separately for API use.

Install

The Composer commands below are for a direct AgenticEcom purchase. If you bought this extension through Adobe Commerce Marketplace, use the purchased Composer package from repo.magento.com with Adobe Marketplace access keys; see Getting Started. A Marketplace purchase should not require a second AgenticEcom direct-store licence.

Install Custom Forms with Composer using your AgenticEcom licence key (find it on your My Licences page — one key unlocks every module you own):

# 1. Register the AgenticEcom repository (once per store)
composer config repositories.agenticecom composer https://repo.agenticecom.net
composer config --global --auth http-basic.repo.agenticecom.net <YOUR-LICENCE-KEY> x

# 2. Require this module
composer require agenticecom/module-customforms:^1.0.3

# 3. Apply it
php bin/magento setup:upgrade && php bin/magento setup:di:compile && php bin/magento cache:flush

Have the whole platform?

Install every module in one command with composer require agenticecom/suite — see Install the complete suite.

Compatibility

Magento

Release 1.0.2 installed, upgraded and compiled on Open Source 2.4.9. Test other 2.4 environments on staging.

PHP

Release QA used 8.5.10. Check Composer requirements and test your PHP version.

Storefront

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

PDF

Composer installs the required mpdf/mpdf dependency for PDF export & email attachments.

What makes this different

Custom Forms ships one tier (no paywalled “Pro”), works with a headless storefront, can sign webhook requests with HMAC-SHA256 when you set a secret, and offers optional OpenAI or Gemini 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 — off by default; when Yes, only ambiguous submissions get a second opinion from OpenAI or Google Gemini.
• OpenAI API Key / Google Gemini API Key — enter your own key for the chosen provider. Both settings are stored encrypted. Each key is sent only to its own provider.
• AI Model — Auto prefers OpenAI GPT-6 Luna if its key is present, while a Google-key-only setup continues with Gemini 3.8 Flash. GPT-6.1 Sol, GPT-6 Astra, Gemini 3.7 Flash and Gemini 3.1 Pro Preview are selectable too. Existing Gemini 2.5 choices remain supported. The retired Gemini 3 Pro Preview selection is migrated.
• Privacy and cost — the module sends at most 1,600 characters after redacting common email addresses, phone-like numbers and URL paths. Other free-text personal information may remain. The provider may charge you for API use. Review your privacy notice and the spam inbox before enabling automatic rejection.

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) — delete uploaded files after N days (0 = never). Uploads use public media URLs; anyone with a link can open a file until deletion.
• 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.

Export & import forms

Move a form between stores — staging → live, or one client site to another — without rebuilding it. Export writes the form’s definition (its fields, content, routing and spam settings) to a portable JSON file; import re-creates it on the target store.

1. Export one form — on the forms grid, open the row’s Select menu and choose Export. You’ll download custom-form-<code>.json.

2. Export several at once — tick the forms you want, then Actions → Export Selected. All of them are written to a single JSON file.

3. Import — on the target store, click Import Forms (top of the grid), choose the .json file, and Import. Each form in the file is created and you’re returned to the grid with a confirmation.

What's included — and what isn't

Export carries the form template only: fields, success message, button/popup text, email routing, captcha, scheduling and display rules. It does not include submissions (those are your respondents’ data and stay put). Tip: exporting a form and importing it back into the same store is a quick way to duplicate it.

After importing, check three things

Imports never overwrite an existing form — each is created new with a unique code (e.g. contact-us-2 if contact-us already exists). Because a few settings reference IDs that differ between stores, review these on each imported form:

• Store View assignment,
• email recipients and the email/autoresponder templates,
• the customer group restriction.

Imported definitions are also sanitised on the way in, so a file from an untrusted source can’t inject scripts.

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 use public links

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. The resulting media URL is public: anyone with the link can open the file. Do not collect sensitive documents unless this access model meets your policy. Set File Upload Links Lifetime and Submission Retention to finite values where appropriate; both default to no automatic deletion when set to 0.

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 (such as excess links and known spam phrases), with conservative handling of ordinary enquiries.

4. AI scoring (OpenAI or Google Gemini) — an optional second opinion for ambiguous submissions, using your own provider key. A provider failure or unusable response falls back to local checks.

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 — delete files and end their public links after N days (0 = never). Anyone with a link can open a file until deletion.
• 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.

Composer dependency

Composer installs this dependency with 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?

The module provides a honeypot, a blocked-keyword list, built-in heuristics, optional OpenAI or Gemini scoring, and optional reCAPTCHA v3 (which fails closed when enabled). 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 by extension and size but are served from public media URLs; secret keys (reCAPTCHA, AI, webhook) are stored encrypted; and webhook payloads are HMAC-signed when a signing secret is configured. Release 1.0.2 installed, upgraded and compiled on Magento Open Source 2.4.9 / PHP 8.5.10.

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, optional OpenAI or Gemini scoring, encrypted keys and model selection
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