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'] = '[email protected]';
}
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'] = '[email protected]';
}
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'] = '[email protected]';
} else {
//not a free email address, send to priority email address
$notification['to'] = '[email protected]';
}
}
//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' => '[email protected]',
),
array(
'fieldId' => 1,
'operator' => 'is',
'value' => 'Support',
'email' => '[email protected]',
),
);
}
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