Using Gravity Forms ‘gform_send_email_failed’ PHP filter

The gform_send_email_failed is an action event triggered when an email sent from Gravity Forms fails to deliver.

Usage

To use this action hook, you can add your custom function to the gform_send_email_failed hook using the add_action() function. Your custom function will be executed when the gform_send_email_failed event occurs.

add_action( 'gform_send_email_failed', 'my_function', 10, 3 );

In the above example, the my_function is the name of your custom function that you want to execute when the gform_send_email_failed event occurs. The number 10 is the priority of your function, and 3 is the number of parameters passed to your function.

Parameters

The gform_send_email_failed action hook has the following parameters that can be used in your custom function:

  • $error (string) – The error message returned from the email failure.
  • $details (array) – An array containing details of the email that failed to send.
  • $entry (array) – The entry object.

More information

  • This action hook was implemented in Gravity Forms version 1.7.
  • Source code location: common.php.
  • See Gravity Forms Docs: gform_send_email_failed

Examples

Here are some practical examples of how to use the gform_send_email_failed action hook:

Send an email notification when an email fails to send

The example below uses the WordPress core wp_mail() function to send an email notification to the site admin when an email from Gravity Forms fails to send.

add_action( 'gform_send_email_failed', function( $error, $details, $entry ) {
    $to = '[email protected]'; // Change this to the admin email address.
    $subject = 'Notification failed!';
    $body = "Notification email '$details[subject]' for entry #$entry[id] failed.";
    wp_mail( $to, $subject, $body );
}, 10, 3 );

Log email failure details

The example below logs the email failure details to the WordPress debug log.

add_action( 'gform_send_email_failed', function( $error, $details, $entry ) {
    GFCommon::log_debug( 'Email failed with error: ' . $error );
    GFCommon::log_debug( 'Email details: ' . print_r( $details, true ) );
    GFCommon::log_debug( 'Entry details: ' . print_r( $entry, true ) );
}, 10, 3 );

Disable email notifications for a specific form

The example below disables email notifications for a specific form when an email from Gravity Forms fails to send.

add_action( 'gform_send_email_failed', function( $error, $details, $entry ) {
    if ( $entry['form_id'] == 1 ) { // Replace 1 with your form ID.
        add_filter( 'gform_disable_notification', '__return_true' );
    }
}, 10, 3 );