Add programmatic form actions

Programmatic forms support the shared email, storage/retention, redirect and presentation behavior supplied by the normalized configuration.

Email routes

Use admin_routes for site recipients and client_routes for a submitter message. Each route can define its recipients, subject, message/data inclusion, upload policy and conditional behavior supported by POM Forms.

Field values are referenced through form merge tags such as:

{{field:contact_email}}
{{field:message}}
{{meta:form_name}}

Use an authorized address on the site's domain as From and a validated submitter field as Reply-To when replies are expected.

Transport preflight

Before dispatching a notification batch, the forms runtime calls pom_mail_preflight for each prepared message. Transport integrations receive true|WP_Error $result and an array containing to, subject, message, headers, and attachments. Return the prior error unchanged, true when preparation succeeds, or WP_Error when delivery is known to be impossible. Validation callbacks must not send mail, enqueue retries or create delivery logs. The pom_mail_message_too_large error code selects the attachment-size feedback.

Without a transport validator, the theme applies no provider-specific size ceiling. Runtime delivery still uses wp_mail(). Mail filters or files changed after validation remain subject to the transport's final checks.

pom_forms_admin_email and pom_forms_client_email run once per selected configuration during preparation. pom_forms_submission_saved runs after the provisional row and all notifications pass preflight, before email dispatch. It does not run for a rejected notification batch.

Storage and retention

Programmatic forms follow the global POM Forms storage policy unless store_submissions_override and retention_override_days intentionally define an allowed override. File storage remains separately controlled. Document every copy created by email, WordPress storage and the owning integration.

Redirect and feedback

Use normalized configuration for success/error messages, optional redirect, loading indicator, scroll-to-message and submit-button behavior. The visitor must receive an understandable terminal state even if an email destination fails.

Deliberate exclusions

pom_render_programmatic_form() forces:

$config['webhook_enabled']     = false;
$config['create_post_enabled'] = false;

Use a saved POM form when editors need those workflows. Do not re-enable them after the preparation helper or call private submission functions directly.