Getting started

This page takes you from a fresh install to a working form on a page. It assumes you know your way around the WordPress admin. You do not need to write any code to follow it.

1. Install and activate

Upload and activate OctaForms like any other plugin. A new OctaForms menu appears in the admin sidebar.

On activation the plugin sets up its own database tables and seeds a ready-to-use starter form called contact. You can use that form straight away, or create your own.

Tip

Nothing is sent anywhere and no form is shown to visitors until you place it on a page yourself. Activating the plugin is safe.

2. Create a form

Go to OctaForms → Add New Form.

1. Give the form a title for your own reference.
2. Set the slug. This is the name your theme and any integrations will use to point at this form. Pick something short and stable, like contact or newsletter.
3. Fill in the config: the fields, validation rules, emails and webhooks. This is a JSON document, and the editor checks it as you type.

The slug locks after publishing

Once a form is published, its slug is fixed. That is on purpose: the slug is a contract that your theme and your webhook receivers rely on, and a form that renames itself would quietly break them. Choose the slug with that in mind.

A minimal contact form config looks like this:

{
  "fields": [
    { "name": "name",    "type": "text",     "label": "Your name", "rules": [{ "r": "required" }] },
    { "name": "email",   "type": "email",    "label": "Email",     "rules": [{ "r": "required" }, { "r": "email" }] },
    { "name": "message", "type": "textarea", "label": "Message",   "rules": [{ "r": "required" }] }
  ],
  "email": {
    "notification": { "enabled": true, "to": ["[email protected]"] }
  }
}

Notice that the email type and the email rule do two different jobs. The type picks the input, so the visitor gets an e-mail keyboard and autofill. The rule checks the value. You add the rule yourself, and the check always runs on the server. That split holds throughout: the type shapes the input, and rules do the checking.

You do not have to write raw JSON if you would rather not. The form editor gives you a structured, tabbed view of the same document. Whichever you use, it is the same single config underneath.

The full shape of the config, all field types, and every validation rule are covered in Building forms.

3. Test it before it goes live

Every form has a test submit panel in the admin. Use it to send a sample submission and see exactly what happens: which validation passes or fails, what the notification email would contain, and what each webhook payload looks like.

Nothing is actually sent from the test panel. It is a safe preview, and it is the fastest way to catch a typo in an email address or a validation rule before a real visitor hits it.

4. Put the form on a page

OctaForms renders no markup on its own, so this step is how the form actually appears to visitors. There are three ways to do it, from quickest to most control:

• The starter shortcode. Drop [octa_form slug="contact"] into any page or post. You get an unstyled, working form immediately. Great for getting live fast or for testing. See the starter shortcode.
• The JS helper. Write your own form markup, add data-octa-forms="contact" to the <form>, and let the bundled helper wire up submission, validation display and the security token for you. See the JS helper.
• Your own JavaScript. Talk to the REST API directly for full control over every request and response. See your own JavaScript.

Not sure which fits you? Three ways to add a form compares them side by side.

5. Read your submissions

Submissions land under OctaForms → Submissions. From there you can:

• Read each submission and its stored consent record.
• Export received submissions to CSV.
• Check the spam quarantine for anything the honeypot caught, and recover a real submission if browser autofill tripped it.

Your configured emails and webhooks fire automatically as submissions come in.

Before you go live for real

If this form is going into production, read the production checklist. The two things that matter most:

• Set up a real cron. WP-Cron only runs when someone visits the site, which can delay delivery. Run wp octa-forms queue drain from a system cron every minute for reliable, timely delivery.
• Set up proper email sending. WordPress reporting an email as “sent” only means your server accepted it, not that it arrived. Use an SMTP plugin and send from a domain with valid SPF and DKIM.

Next steps

• Learn the config in depth: The config JSON.
• Wire it into your theme: Three ways to add a form.