Add a contact form to WordPress.

1. Check your site

You need permission to save custom form markup. On self-hosted WordPress, account roles, multisite rules or security settings can restrict HTML. Save a draft and reopen the block to confirm the form tags remain.

On WordPress.com, form, input and textarea tags require a plugin-enabled plan with hosting features activated. A free site’s Custom HTML block alone is not enough. Check the current WordPress.com code restrictions.

This creates a standalone HTML form. It does not wire up Contact Form 7, WPForms or a page builder’s native form widget. See the WordPress integration overview to decide whether this fits your workflow.

2. Create a form and add the block

1. Sign in to Form Koi, create a form and select a verified notification recipient.
2. Copy the complete public endpoint from the form’s connection guide. Configure its honeypot field name to match the example, or copy the generated HTML that matches your settings.
3. Open your contact page in the WordPress block editor. Add a Custom HTML block using the block inserter or type /html. Do not use the Code block.
4. Paste the markup below and replace the entire action URL with your endpoint. Keep a name on each field you want to receive.

<form action="https://api.formkoi.com/f/YOUR_PUBLIC_FORM_KEY" method="POST">
  <label for="name">Your name</label>
  <input id="name" name="name" autocomplete="name" required>

  <label for="email">Email address</label>
  <input id="email" name="email" type="email" autocomplete="email" required>

  <label for="message">Your message</label>
  <textarea id="message" name="message" required></textarea>

  <!-- Leave this hidden anti-spam field empty. -->
  <input type="text" name="botcheck"
    tabindex="-1" autocomplete="off" style="display:none" hidden>

  <button type="submit">Send message</button>
</form>

The example endpoint is a placeholder. It cannot deliver messages until replaced. The public form key belongs in the markup; management API tokens and Turnstile secrets do not.

The example has no Turnstile widget or file uploads. If you enable either feature, use the updated HTML from your connection guide. Turnstile needs its script and widget to survive WordPress’s HTML filtering; follow the protection guide and verify the published page before enforcing it.

Your theme may style the inputs and button. Add CSS through your theme’s supported customization method if needed. If you use a full-page form template, place only the form markup in the block, not a second HTML document.

The WordPress Custom HTML documentation explains the editor and permission-dependent code controls.

3. Publish and test the actual page

1. Set allowed origins in Form Koi to your exact public website origin, including HTTPS and the correct www or non-www hostname.
2. Create a thank-you page in WordPress and set its full HTTPS URL in Form Koi’s form settings. This native form navigates after submission; it does not show an inline success message.
3. Save or publish your contact page. Open its public URL while logged out, and test required fields, keyboard navigation and the mobile layout.
4. Send a distinct test message. Find it in the Form Koi Inbox, check its fields and review notification history. Check Spam if the message is missing.
5. Confirm the notification reaches your recipient. Stored submissions and successful email delivery are separate events. Staging notifications stay in the internal test inbox.

Keep the hidden honeypot empty. Check your submission allowance and provide another way to contact you if the form is unavailable. For inline feedback, see the JavaScript example; custom scripts must also be permitted on your WordPress site.

Troubleshoot a WordPress contact form

The page shows code, or fields disappear after saving

Confirm you used Custom HTML rather than Code. If form or input tags disappear when you reopen the saved block, check your account’s HTML permissions and your host’s restrictions with the site administrator.

The form reloads WordPress or goes to the wrong URL

Inspect the published form’s action and method: it should POST to your complete Form Koi endpoint. Check for a placeholder URL, removed attributes or another form wrapped around your block. Clear page caches after editing and test again while logged out.

Form Koi rejects the submission

Check the response against the submission API guide. Confirm the published origin matches your allowed origins, the honeypot name matches your settings, and any required Turnstile widget can load and produce a token. A 429 response can indicate a rate or allowance limit.

The message is stored but no email arrives

Check the selected verified recipient, Spam and notification delivery history in Form Koi. Changing a WordPress SMTP plugin will not affect this form because its submission goes directly to Form Koi. See email delivery tracking.