gform_notification

Description

Modify a notification object before it is converted into an email and sent.

Usage

The following would apply to all forms:

add_filter( 'gform_notification', 'your_function_name', 10, 3 );

To target a specific form append the form id to the hook name. (format: gform_notification_FORMID)

add_filter( 'gform_notification_5', 'your_function_name', 10, 3 );

Parameters

  • $notification array

    An array of properties which make up a notification object. See Notifications Object for possible properties.

  • $form Form Object

    The form object for which the notification is being sent.

  • $entry Entry Object

    The entry object for which the notification is being sent.

Examples

1. Append text to message

This example demonstrates how you can use the gform_notification filter to append a signature to all outgoing Gravity Form notifications.

add_filter( 'gform_notification', 'my_gform_notification_signature', 10, 3 );
function my_gform_notification_signature( $notification, $form, $entry ) {
       // append a signature to the existing notification
       // message with .=
    $notification['message'] .= "n --The Team @ rocketgenius";

    return $notification;
}

2. Change to or toType settings for user notification

This example demonstrates how to update old code that is using the deprecated gform_autoresponder_email hook

add_filter( 'gform_notification', 'change_autoresponder_email', 10, 3 );
function change_autoresponder_email( $notification, $form, $entry ) {

    // There is no concept of user notifications anymore, so
    // we will need to target notifications based on other
    // criteria, such as name
    if ( $notification['name'] == 'User Notification' ) {

        // toType can be routing or email
        $notification['toType'] = 'email';
        // change the "to" email address
        $notification['to'] = 'test@test.com';

    }

    return $notification;
}

3. Change to or toType settings for admin notification

This example demonstrates how to update old code that is using the deprecated gform_notification_email hook

add_filter( 'gform_notification', 'change_notification_email', 10, 3 );
function change_notification_email( $notification, $form, $entry ) {

    //There is no concept of admin notifications anymore, so we will need to target notifications based on other criteria, such as name
    if ( $notification['name'] == 'Admin Notification' ) {

        // toType can be routing or email
        $notification['toType'] = 'email';
        $notification['to'] = 'test@test.com';

    }

    return $notification;
}

4. Change the message format

The default message format for notifications is html, however, you can change the format to text or multipart.

This example also demonstrates how to update old code that is using the deprecated gform_notification_format hook.

add_filter( 'gform_notification', 'change_notification_format', 10, 3 );
function change_notification_format( $notification, $form, $entry ) {
     GFCommon::log_debug( 'gform_notification: change_notification_format() running.' );
    // Do the thing only for a notification with the name Text Notification
    if ( $notification['name'] == 'Text Notification' ) {
        GFCommon::log_debug( 'gform_notification: format changed to text.' );
        // Change notification format to text from the default html
        $notification['message_format'] = 'text';
    }

    return $notification;
}

5. Attach single file uploads

As of Gravity Forms 2.4, there is an option in the Notification to attach files uploaded from the File Upload field. This example is not necessary, unless you are filtering which files to include.

This example demonstrates how to update old code that is using the deprecated gform_user_notification_attachments hook and applies to single file upload fields only.

add_filter( 'gform_notification', 'change_user_notification_attachments', 10, 3 );
function change_user_notification_attachments( $notification, $form, $entry ) {

	//There is no concept of user notifications anymore, so we will need to target notifications based on other criteria, such as name
	if ( $notification['name'] == 'User Notification' ) {

		$fileupload_fields = GFCommon::get_fields_by_type( $form, array( 'fileupload' ) );

		if ( ! is_array( $fileupload_fields ) )
			return $notification;

		$notification['attachments'] = ( is_array( rgget('attachments', $notification ) ) ) ? rgget( 'attachments', $notification ) : array();
		$upload_root = RGFormsModel::get_upload_root();
		foreach( $fileupload_fields as $field ) {
			$url = $entry[ $field->id ];
			$attachment = preg_replace( '|^(.*?)/gravity_forms/|', $upload_root, $url );
			if ( $attachment ) {
				$notification['attachments'][] = $attachment;
			}
		}

	}

	return $notification;
}

6. Attach single or multi-file file uploads

As of Gravity Forms 2.4, there is an option in the Notification to attach files uploaded from the File Upload field. This example is not necessary, unless you are filtering which files to include.

Use this example if you have the multi-file uploads option selected:

add_filter( 'gform_notification', 'rw_notification_attachments', 10, 3 );
function rw_notification_attachments( $notification, $form, $entry ) {
	$log = 'rw_notification_attachments() - ';
	GFCommon::log_debug( $log . 'starting.' );

	if ( $notification['name'] == 'Admin Notification' ) {

		$fileupload_fields = GFCommon::get_fields_by_type( $form, array( 'fileupload' ) );

		if ( ! is_array( $fileupload_fields ) ) {
			return $notification;
		}

		$notification['attachments'] = rgar( $notification, 'attachments', array() );
		$upload_root = RGFormsModel::get_upload_root();

		foreach( $fileupload_fields as $field ) {

			$url = rgar( $entry, $field->id );

			if ( empty( $url ) ) {
				continue;
			} elseif ( $field->multipleFiles ) {
				$uploaded_files = json_decode( stripslashes( $url ), true );
				foreach ( $uploaded_files as $uploaded_file ) {
					$attachment = preg_replace( '|^(.*?)/gravity_forms/|', $upload_root, $uploaded_file );
					GFCommon::log_debug( $log . 'attaching the file: ' . print_r( $attachment, true  ) );
					$notification['attachments'][] = $attachment;
				}
			} else {
				$attachment = preg_replace( '|^(.*?)/gravity_forms/|', $upload_root, $url );
				GFCommon::log_debug( $log . 'attaching the file: ' . print_r( $attachment, true  ) );
				$notification['attachments'][] = $attachment;
			}

		}

	}

	GFCommon::log_debug( $log . 'stopping.' );

	return $notification;
}

7. Change to setting depending on users email

This example checks to see if the email address entered by a user matches certain strings to send the notification to a special email address for handling.

//target form id 203, change to your form id
add_filter( 'gform_notification_203', 'set_email_to_address', 10, 3 );
function set_email_to_address( $notification, $form, $entry ) {
    //There is no concept of user notifications anymore, so we will need to target notifications based on other criteria,
    //such as name
    if ( $notification['name'] == 'Admin Notification' ) {
        //get email address value
        $user_email = rgar( $entry, '1' ); //value for field id 1, change to your field id

        //set email to address based on email address user entered
        //gmail.com, hotmail.com, aol.com, yahoo or live.com
        //look for special email addresses in user email string
        if ( strpos( $user_email, 'gmail.com' ) || strpos( $user_email, 'hotmail.com' ) || strpos( $user_email, 'aol.com' ) || strpos( $user_email, 'yahoo.com' ) || strpos( $user_email, 'live.com' ) ) {
            //user entered email address matching free email addresses, send to special address
            $notification['to'] = 'special@example.com';
        } else {
            //not a free email address, send to priority email address
            $notification['to'] = 'priority@example.com';
        }
    }
    //return altered notification object
    return $notification;
}

8. Configure routing

This example shows how you can define routing rules.

add_filter( 'gform_notification', 'notification_routing', 10, 3 );
function notification_routing( $notification, $form, $entry ) {
    if ( $notification['name'] == 'Admin Notification' ) {
        $notification['toType']  = 'routing';
        $notification['routing'] = array(
            array(
                'fieldId'  => 1,
                'operator' => 'is',
                'value'    => 'Sales',
                'email'    => 'sales@domain.com',
            ),
            array(
                'fieldId'  => 1,
                'operator' => 'is',
                'value'    => 'Support',
                'email'    => 'support@domain.com',
            ),
        );
    }

    return $notification;
}

9. Use values from a List field

This example shows how you can use the values from a List field column as the TO address.

add_filter( 'gform_notification_100', 'notification_emails_from_list_field', 10, 3 );
function notification_emails_from_list_field( $notification, $form, $entry ) {
    // only change notification to address for this specific notification
    if ( $notification['name'] == 'User Notification' ) {

        $field_id   = 2; // the id of the list field
        $column_num = 3; // the number of column that holds the emails

        // get the $field object for the provided id
        $field = RGFormsModel::get_field( $form, $field_id );

        // check the field type as we only want the rest of the function to run if the field type is list
        if ( $field->get_input_type() != 'list' ) {
            return $notification;
        }

        // count the actual number of columns
        $column_count = count( $field->choices );

        if ( $column_count > 1 ) {
            // subtract 1 from column number as the choices array is zero based
            $column_num = $column_num - 1;

            // get the column label so we can use that as the key to the multi-column values
            $column = rgars( $field->choices, "{$column_num}/text" );
        }

        // get the list fields values from the $entry
        $list_values = unserialize( $entry[ $field_id ] );
        $emails      = array();

        foreach ( $list_values as $value ) {
            // get the emails for each row
            $email = isset( $column ) ? $value[ $column ] : $value;
            if ( GFCommon::is_valid_email( $email ) ) {
                $emails[] = $email;
            }
        }

        // replace the to address with a comma separated list of emails
        $notification['to'] = GFCommon::implode_non_blank( ',', $emails );
    }

    return $notification;
}

10. Attach specific file

This example shows how you can attach a specific file to the notification.

add_filter( 'gform_notification_2', 'add_attachment_pdf', 10, 3 ); //target form id 2, change to your form id
function add_attachment_pdf( $notification, $form, $entry ) {
	//There is no concept of user notifications anymore, so we will need to target notifications based on other criteria,
	//such as name or subject
	if( $notification['name'] == 'User Notification' ) {
		//get upload root for WordPress
		$upload = wp_upload_dir();
		$upload_path = $upload['basedir'];

		// Add file, use server absolute full path to your file.
		$attachment = $upload_path . '/test.txt';

		GFCommon::log_debug( __METHOD__ . '(): file to be attached: ' . $attachment );

		if ( file_exists( $attachment ) ) {
			$notification['attachments']   = rgar( $notification, 'attachments', array() );
			$notification['attachments'][] = $attachment;
			GFCommon::log_debug( __METHOD__ . '(): file added to attachments list: ' . print_r( $notification['attachments'], 1 ) );
		} else {
			GFCommon::log_debug( __METHOD__ . '(): not attaching; file does not exist.' );
		}
	}
	//return altered notification object
	return $notification;
}

Placement

This code should be placed in the functions.php file of your active theme.

Source Code

This filter is located in GFCommon::send_notification() in common.php