GoBuildWPDocs
Get started free
Pro module2 also in Free11 abilities

Contact Form 7 ability reference

Reference for the GoBuildWP Pro 1.12.4 and Free 1.18.6 source. Installed schemas and policy remain authoritative.

This Contact Form 7 ability reference covers how an agent lists, reads, creates, edits, duplicates and deletes Contact Form 7 forms, checks which form-tags it may use, and, on sites running Flamingo, lists and exports the messages Flamingo saved for each form.

By GoBuildWPContent updated How we check claims

Read-only, write and destructive groups describe the source annotations. They do not establish a minimum safety profile, human approval or undo support. Those controls are separate: check the installed ability, the connected user and the active site policy before calling it. A read can still return sensitive data. These pages are not evidence that every operation passed an end-to-end runtime test.

What Contact Form 7 needs before these load

2 of the 11 also ship in GoBuildWP Free 1.18.6 under the same names, marked “Also in GoBuildWP Free” below. They need no GoBuildWP Pro licence, but each retains its own dependency, feature and permission checks. Where Free's copy does less, its own description follows Pro's. When Pro's richer copy passes its gates, it registers first and answers.

Contact Form 7 5.8.0 or newer is required: the gate needs WPCF7_VERSION, the WPCF7_ContactForm class and a version at or above WPPILOT_PRO_CF7_MIN_VERSION. Flamingo is an optional companion from 2.4; without it the entry calls stay registered and answer cf7_flamingo_inactive, with a message that says whether Flamingo is missing or too old. Every call uses GoBuildWP's standard check (abilities switched on, manage_options, or super admin on multisite). Reading entries also needs flamingo_edit_inbound_messages, the capability behind Flamingo's own inbox, or the call returns cf7_capability_missing. The free plugin's cf7-list-entries also cuts email addresses and phone numbers out of answers and the subject and takes no include_sensitive; form writes, the tag schema and export are Pro.

Minimum (base)
5.8.0 WPPILOT_PRO_CF7_MIN_VERSION
Minimum (companion)
2.4 WPPILOT_PRO_FLAMINGO_MIN_VERSION
Contact Form 7 editions
free
Agent skills shipped
cf7-integration, form-model-schema, form-model-migration

No Flamingo, no stored submissions

Contact Form 7 emails a submission and keeps nothing. Flamingo, by the same author, saves each one as a flamingo_inbound post tagged with a flamingo_inbound_channel term that CF7 creates for the form when its earliest submission is stored and remembers in the form's _flamingo meta; older forms are matched by slug. Messages sent before Flamingo was active were not stored by CF7 or Flamingo; unless another storage plugin kept them, only the notification emails hold them.

cf7-list-entries returns compact rows (id, date, status, subject) with no field values, up to 200 per page, filtered by inbox, spam, trash or any. cf7-export-entries produces CSV or JSON with one column per form-tag name, since CF7 fields have no separate labels, in pages of up to 5,000 rows followed by a cursor. File-upload, password-like and card-like columns and the IP are "[REDACTED]" unless the call sends include_sensitive=true with confirm=true after the user asked for them; the same pair is needed before search looks inside those fields.

How a form is stored and patched

Each form is a wpcf7_contact_form post whose postmeta keys (_form, _mail, _mail_2, _messages, _additional_settings, _locale) hold the template, both mail configurations, messages and settings, surfaced unchanged so they read like CF7's own documentation. cf7-edit-form changes the keys you pass and leaves the rest, merging mail, mail_2 and messages key by key, so mail.recipient can change without resending the body. CF7's save() rewrites all six keys from memory, so edits to one form are serialised with a MySQL advisory lock; where the host cannot lock, the response carries a warning. Mail changes fire wppilot_cf7_form_changed with before and after snapshots for audit plugins.

Deleting is permanent by default: the form skips the trash, pages embedding its shortcode start showing CF7's missing-form message, and no ability brings it back. Passing force=false sends it to Forms > Trash instead.

Representative call sequence

This sequence describes the documented calls and checks to perform. It is not a recorded result from an installed WordPress site. Inspect returned errors and partial results, then verify the saved values and affected output before proceeding.

Add a phone number field to the contact form and see what arrived this week.

  1. 01 wppilot/cf7-get-tags-schema Describes the tel form-tag and its options, so the new field uses valid CF7 syntax.
  2. 02 wppilot/cf7-get-form Returns the current template and mail settings for the form id.
  3. 03 wppilot/cf7-edit-form Sends the whole template back with the new tel field added, since the form string is replaced rather than merged. CF7 emails only fields whose mail-tag appears in the mail body, so if the phone number should reach the notification, patch mail.body with that tag in the same call; keys not sent keep their stored values.
  4. 04 wppilot/cf7-list-entries Lists this week's Flamingo messages for the form by date and subject, or returns cf7_flamingo_inactive if Flamingo is absent.

Questions about Contact Form 7

Why does cf7-list-entries return cf7_flamingo_inactive?

Contact Form 7 does not keep submissions, and Flamingo is either not active or older than 2.4. Once Flamingo runs it stores new messages; earlier ones were not stored by either plugin, so only the notification emails (or another storage plugin) can still hold them.

Can the agent export uploaded files or visitor IPs?

Not by default. With GoBuildWP Pro those columns are redacted unless the call carries include_sensitive=true with confirm=true, which the agent should send just after the user explicitly asks. GoBuildWP Free has no export and never returns them.

Can a deleted form be recovered?

Not from GoBuildWP when it was force-deleted, which is the default; only a database backup taken before the delete can bring it back. Delete with force=false to trash it instead, and it can be restored from Forms > Trash in wp-admin.

Contact Form 7 reads

AbilityWhat it does
wppilot/cf7-check-setupCheck Contact Form 7 SetupReturns a snapshot of the Contact Form 7 install: whether the plugin is active, its version, whether the minimum supported release is satisfied, the count of saved forms, the current user's CF7 capabilities (edit / read / delete), and whether the Flamingo companion plugin is active (Flamingo is the standard way to persist CF7 submissions - without it CF7 keeps no record of who submitted what, and reading submissions is not possible). Call this once at the start of any session that will read or write CF7 forms.
wppilot/cf7-export-entriesExport Contact Form 7 Entries (Flamingo)Export the Flamingo-stored submissions of one Contact Form 7 form as CSV or JSON, one column per form-tag name (CF7 fields have no separate labels). CF7 itself stores nothing — without the Flamingo plugin this returns cf7_flamingo_inactive. Filters: status (inbox | spam | trash | any), date_from / date_to, search (the subject and any field value; the redacted file-upload, password-like and card-like fields and the IP are searched only with include_sensitive=true and confirm=true). Up to 5000 rows per call (a ~200 KiB budget may stop sooner); pass next_cursor back as cursor until it is null. File-upload, password-like and IP columns are [REDACTED] unless include_sensitive=true with confirm=true.
wppilot/cf7-get-formGet Contact Form 7 FormReads a single Contact Form 7 form by id, including the full template (form), both mail configurations (mail and mail_2, with mail_2.active=false when the secondary mail is disabled), all message strings (messages), the additional-settings blob, locale and hash. Large text fields (form, mail.body, mail_2.body, additional_settings) are truncated at max_field_bytes (default 8192) per field with a *_truncated flag and *_bytes (original byte length) so the agent can decide whether to re-read at a higher cap. Set max_field_bytes to 0 to disable truncation. Returns WP_Error cf7_form_not_found when the id does not exist or refers to a trashed / auto-draft / non-CF7 post.
wppilot/cf7-get-form-canonicalGet Contact Form 7 Form (Canonical)Reads a single Contact Form 7 form by id and returns it mapped to the plugin-agnostic form-model-schema vocabulary (17 canonical types: text/email/tel/url/number/textarea/date/time/datetime/select/radio/checkbox/file/hidden/submit/consent/group) used by the form-model-migration skill. CF7 natively covers 14 of those 17 - time/datetime/group have no CF7 form-tag and appear only on migration targets. Output keys: fields[] with canonical types, mail_config{} for the primary mail, notifications[] for mail_2 (when active), messages{} flat string map, meta{} (source plugin + version + optional cf7_additional_settings echo), plus warnings[] for everything that does not fit the canonical shape (CF7 [quiz] anti-spam, [recaptcha] site-global keys, [response] output area, non-empty additional_settings, special mail-tags, [acceptance optional]). Honours the same max_field_bytes truncation contract as cf7-get-form (default 8192 bytes for mail_config.body, notifications[].body, meta.cf7_additional_settings, with *_truncated flags); pass max_field_bytes: 0 to disable truncation when full-fidelity canonical is required before an execute-mode migration. Returns WP_Error cf7_form_not_found when the id does not exist or refers to a trashed / auto-draft / non-CF7 post. Use this ability inside the form-model-migration workflow (Phase 2 - read source schema); for ad-hoc inspection outside the migration pipeline, prefer cf7-get-form which returns the CF7-native shape.
wppilot/cf7-get-tags-schemaGet Contact Form 7 Tag SchemaReturns the Contact Form 7 form-tag vocabulary: every tag type CF7 accepts in a form template (text, email, tel, url, number, date, textarea, select, checkbox, radio, file, acceptance, quiz, submit, hidden, response, plus module tags recaptcha), what each one renders, which modifiers it accepts, and a short example. Pass type to receive only that single entry. Call this once before composing a form template so cf7-create-form and cf7-edit-form receive valid syntax on the first try. NOTE: the label / description / example strings are English-only (this is a static reference, not a translated catalogue) - translate them on the agent side if needed.
wppilot/cf7-list-entriesList Contact Form 7 Entries (Flamingo)Also in GoBuildWP FreeList the submissions Flamingo stored for one Contact Form 7 form, newest first. CF7 itself stores nothing — without the Flamingo plugin this returns cf7_flamingo_inactive. Filters: status (inbox | spam | trash | any), date_from / date_to, search (the subject and any field value; file-upload, password-like and card-like fields and the IP are searched only with include_sensitive=true and confirm=true). Paginated with limit (default 25, max 200) and offset. Compact rows {id, date, status, subject} with no field values — use cf7-export-entries for the values.

In GoBuildWP Free: List the submissions Flamingo stored for one Contact Form 7 form, newest first, with their answers: id, date, status, subject and answers (field_id and label are the form-tag name, type its base type, value). Contact Form 7 itself stores nothing: without the Flamingo plugin this returns cf7_flamingo_inactive. Filters: status (inbox | spam | trash | any, default inbox), date_from / date_to (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS, inclusive). limit defaults to 20 (max 100), offset pages. Contact details and sensitive fields are withheld (names and other answers are not):email and phone answers, passwords, card data, file uploads and signatures come back as "[REDACTED]" with a redacted reason, and email addresses or phone numbers typed into any other answer or the subject are cut out of it (redacted: "contact_in_text"); the submitter's IP is never returned. There is no option to return them here; the full values need the Pro edition (with the person's explicit approval) or Flamingo's Inbound Messages screen.

wppilot/cf7-list-formsList Contact Form 7 FormsAlso in GoBuildWP FreeLists Contact Form 7 forms with optional filters. Response is a compact summary per form - id, title, slug, status, locale, hash, tag_count, modified - WITHOUT the heavy properties (form template, mail, mail_2, messages, additional_settings) so listings stay small. Call cf7-get-form with a specific id to read the full body. Filters: status (publish|draft|pending|private|trash - defaults to publish+draft, trash must be requested explicitly), locale (e.g. "it" or "en_US"), search (case-insensitive substring against title and slug). Pagination: limit (default 50, hard cap 500 enforced by the schema - out-of-range values are rejected at the REST/MCP layer; direct PHP callers are clamped defensively), offset (default 0, must be ≥0). total in the response always reflects the unpaginated match count so the agent knows whether to keep paging. NOTE: under WPML or Polylang the query is scoped to the current admin language by the plugins' own pre_get_posts filters - call check-setup first to detect wpml_active/polylang_active if cross-language enumeration matters.

In GoBuildWP Free: Lists Contact Form 7 forms with optional filters. Response is a compact summary per form — id, title, slug, status, locale, hash, tag_count, modified — without the template, mail settings and messages. Filters: status (publish|draft|pending|private|trash — defaults to publish+draft, trash must be requested explicitly), locale (e.g. "it" or "en_US"), search (case-insensitive substring against title and slug). Pagination: limit (default 50, max 500), offset (default 0). total is the unpaginated match count. Under WPML or Polylang the query is scoped to the current admin language by those plugins' own filters.

Contact Form 7 writes

AbilityWhat it does
wppilot/cf7-create-formCreate Contact Form 7 FormCreates a new Contact Form 7 form. Required: title. Optional: slug (CPT post_name - defaults to a slugified title), status (publish|draft, default publish), locale (e.g. "it" or "en_US"), form (template body using CF7 form-tag syntax - call cf7-get-tags-schema for the vocabulary), mail (primary mail config), mail_2 (secondary mail config), messages (validation / mail / spam strings), additional_settings (newline-separated key:value pairs CF7 modules read - e.g. "demo_mode: on"). Properties left out fall back to the CF7 default template for the requested locale. WP-native aliases accepted: post_title ↔ title, post_name ↔ slug, post_status ↔ status. Returns the full form shape (same as cf7-get-form).
wppilot/cf7-duplicate-formDuplicate Contact Form 7 FormClones an existing Contact Form 7 form into a new row. Every canonical property (form, mail, mail_2, messages, additional_settings, locale) is copied verbatim; the new form receives a fresh hash and a new id. Optional title overrides the duplicate's post_title (defaults to the source title plus " (copy)"). Useful when an agent wants to A/B a contact form, localise an existing form for a new region, or stage edits without touching the live original.
wppilot/cf7-edit-formEdit Contact Form 7 FormMerges new field values into an existing Contact Form 7 form identified by id. Only the keys you pass are changed - omitted keys keep their current value. For nested objects (mail, mail_2, messages) the merge is shallow per-key so you can patch only mail.recipient without losing the rest of the mail config. Use cf7-get-form first to read the current state, then call this with only the keys to change. WP-native aliases accepted: post_title ↔ title, post_name ↔ slug, post_status ↔ status. Returns the full form shape after the merge.

Destructive Contact Form 7 calls

AbilityWhat it does
wppilot/cf7-delete-formDelete Contact Form 7 FormPermanently removes a Contact Form 7 form by id. Force-delete by default - the form does NOT go to trash, it is gone. There is no undo via the abilities. Any page or post that embeds the form's shortcode ([contact-form-7 id="<id>"]) will start rendering the CF7 "this contact form does not exist" message after the delete. Set force to false to trash the form instead (it can then be restored from wp-admin → Forms → Trash).

For the task-level view of Contact Form 7, with worked requests and what to check afterwards, see Contact Form 7 integration page.