Email Customization Hooks

Customize submission email recipients and field output with the two email filters.

Free & PRO · Developer Last reviewed

Elzo Forms sends one notification email per submission when the form has email notifications enabled. Two filters change that email: one adjusts the recipients and whether it is sent at all, the other adjusts how each field appears in the message.

Both filters are available in Elzo Forms Free and PRO.

How the notification is built

Understanding the order helps in choosing the right filter:

  1. The submission is validated, saved, and checked for spam.
  2. elzo_forms_submission_email_settings filters the recipients and the on/off switch.
  3. If notifications are on, the subject and message are read from the form’s text settings.
  4. The template at templates/email/admin-email.php renders the field table, applying elzo_forms_admin_email_field to each field.
  5. WordPress sends the message with wp_mail().

elzo_forms_submission_email_settings

Type: Filter

Arguments: $settings, $form, $submission, $submission_post_id

Runs: after the submission is saved, before the email is composed.

$settings has exactly two keys:

Key Type Meaning
email_notifications string yes sends the notification. Any other value, including no, skips it.
email_notification_recipients string or array Recipients. A string may separate addresses with commas or newlines; an array of addresses is also accepted.

Route a form’s notifications to a different team:

<?php
add_filter( 'elzo_forms_submission_email_settings', function ( $settings, $form, $submission, $submission_post_id ) {
    if ( 12 !== (int) $form->get_id() ) {
        return $settings;
    }

    $settings['email_notification_recipients'] = 'sales@example.com, crm@example.com';

    return $settings;
}, 10, 4 );

Or suppress the notification for submissions you do not want to be told about:

<?php
add_filter( 'elzo_forms_submission_email_settings', function ( $settings, $form, $submission, $submission_post_id ) {
    foreach ( $submission->get_fields() as $field ) {
        if ( 'newsletter_only' === ( $field['field_key'] ?? '' ) && ! empty( $field['value'] ) ) {
            $settings['email_notifications'] = 'no';
        }
    }

    return $settings;
}, 10, 4 );

The filter changes only this submission. It does not modify the form’s stored settings, which is also how PRO’s Mail settings action applies its override.

Note: the submission is already saved when this filter runs. Turning notifications off suppresses the email, not the entry.

elzo_forms_admin_email_field

Type: Filter

Arguments: $field

Runs: once per field while the email body is rendered.

The template reads three keys from the returned array:

Key Used for
admin_label The row label. Takes precedence over label.
label The row label when admin_label is empty.
value The row value. An array is joined with commas; an empty value renders as -. 
<?php
add_filter( 'elzo_forms_admin_email_field', function ( $field ) {
    if ( 'card_number' === ( $field['field_key'] ?? '' ) ) {
        $field['value'] = '****';
    }

    return $field;
} );

Warning: this filter cannot remove a row. The template outputs a table row for every submitted field regardless of what the filter returns, so emptying a field produces a row with - rather than no row. Mask sensitive values here, and prevent them from being collected or stored in the first place if they must not appear at all.

Values are escaped with esc_html() after the filter, so HTML returned in value is displayed as text rather than rendered.

What these filters cannot change

The notification’s subject, headers, and layout are not filterable:

  • The subject is built from the form’s Email notification subject text, the primary field value, and the submission ID.
  • The headers are fixed at Content-Type: text/html; charset=UTF-8.
  • The template is loaded directly rather than through the template loader, so it cannot be overridden from a theme. See Template Overrides.

Because the message is sent with wp_mail(), WordPress’s own filters still apply. Use them for anything the Elzo Forms filters do not reach:

WordPress filter Changes
wp_mail_from The sender address.
wp_mail_from_name The sender name.
wp_mail The full argument set, including subject and headers.
phpmailer_init The mailer instance, for SMTP or a reply-to address. 
<?php
add_filter( 'wp_mail_from_name', function ( $name ) {
    return get_bloginfo( 'name' ) . ' Forms';
} );

Note: wp_mail_from and wp_mail_from_name apply to every email WordPress sends, not only Elzo Forms notifications. Scope the callback if the site sends other mail.

Sending additional emails

These two filters adjust the single built-in notification. To send a different email — a confirmation to the visitor, or an alert to a second team under specific conditions — use the PRO Send email action, which supports its own recipients, subject, message, and conditions. See Automation Actions.

Without PRO, send additional mail from elzo_forms_after_submission_saved, which receives the saved submission.

Next steps

 
Contact us