Form Actions

Form actions are tasks that run after a successful form submission. They are configured in the Actions tab when editing a form. You can add multiple actions to a single form and they will all execute in order.

Built-in Action Types

Core Forms ships with these action types:

• Send Email – Send an email notification to a specified address.
• Auto-Responder – Send a confirmation email to the person who submitted the form.
• Trigger Webhook – Send form data to an external URL via POST request.
• Subscribe to Mailchimp – Add the submitter to a Mailchimp list (requires MC4WP plugin).
• Add to MailerPress – Add the submitter as a MailerPress contact (requires MailerPress plugin).

Adding Actions to a Form

1. Edit your form and go to the Actions tab.
2. Click the dropdown to select an action type.
3. Click Add Action.
4. Configure the action settings.
5. Click Save Changes.

You can add multiple actions of the same type. For example, you could have two “Send Email” actions: one to notify the site admin and another to notify a department manager.

Action Execution

Actions only run on successful submissions. If validation fails (missing required fields, invalid email, spam detection, CAPTCHA failure), no actions are executed.

Actions run synchronously during the AJAX request. They execute in the order they appear in the Actions tab.

Spam submissions never trigger actions, even though the user sees a success message. This is by design to prevent bots from triggering email notifications.

How Actions Work Internally

Each action type is a PHP class that extends Core_Forms\Actions\Action. The base class provides:

• hook() – Registers the action type with the cf_available_form_actions filter, hooks settings rendering, and hooks the process method.
• page_settings($settings, $index) – Renders the action’s configuration UI in the admin.
• process($settings, $submission, $form) – Executes the action when a form is submitted.

The processing flow:

1. User submits the form.
2. Validation passes.
3. Submission is saved to the database (if enabled).
4. The cf_form_success action fires.
5. For each configured action, cf_process_form_action_{type} fires with the action settings, submission, and form.
6. The action’s process() method runs.

Data Variables in Actions

Most action settings support data variables (the [field_name] syntax). This means you can use submitted field values in:

• Email “To” address (e.g., [manager_email])
• Email subject line (e.g., New inquiry from [name])
• Email message body
• Email headers
• Webhook URLs (though typically not needed)

See the Template Variables chapter for the full list of available variables.

Registering Custom Action Types

You can create your own action type by extending the Action base class:

namespace My_Plugin;

use Core_Forms\Actions\Action;
use Core_Forms\Form;
use Core_Forms\Submission;

class MyCustomAction extends Action {

    public $type  = 'my_custom';
    public $label = 'My Custom Action';

    public function page_settings( $settings, $index ) {
        $settings = array_merge( array(
            'api_key' => '',
        ), $settings );
        ?>
        <input type="hidden" name="form[settings][actions][<?php echo $index; ?>][type]" value="<?php echo $this->type; ?>" />
        <p>
            <label>API Key</label>
            <input type="text" name="form[settings][actions][<?php echo $index; ?>][api_key]"
                   value="<?php echo esc_attr( $settings['api_key'] ); ?>" class="regular-text" />
        </p>
        <?php
    }

    public function process( array $settings, Submission $submission, Form $form ) {
        // Your custom logic here
        // $settings contains the configured values
        // $submission->data contains the submitted field data
        // $form has all form properties
    }
}

// Register the action
$action = new MyCustomAction();
$action->hook();

The hook() method on the base class registers everything automatically. Your custom action will appear in the action type dropdown in the admin.