Adding a New Notification Service Using the Add-On Framework

Introduction
The Hooks
Add the Service
Intercept the Notification
Send the Email
Further Reading

Introduction

Gravity Forms 1.9.16 added the ability for the user to select which service is used to send the notification; on a default install only WordPress (wp_mail()) will be available.

The Hooks

Adding a new service can be accomplished using a minimum of two hooks in the init function of your add-on.

/**
 * Plugin starting point. Handles hooks, loading of language files, and PayPal delayed payment support.
 */
public function init() {

	parent::init();

	add_filter( 'gform_notification_services', array( $this, 'add_notification_service' ) );
	add_filter( 'gform_pre_send_email', array( $this, 'maybe_send_email' ), 19, 3 );

}

Add the Service

The gform_notification_services filter is used to add the new choice to the “Email Service” setting on the edit notification page.

This example assumes that your add-on has an initialize_api() function used to include the API files and connect to the service to validate any API credentials. If the credentials are valid, the choice for the new service will be added.

/**
 * Add the new notification service.
 *
 * @param array $services The notification services.
 *
 * @return array
 */
public function add_notification_service( $services ) {

	// If the API can be initialized, add the service.
	if ( $this->initialize_api() ) {
		$services['the_service_name'] = array(
			'label' => esc_html__( 'The Service Name', 'sometextdomain' ),
			'image' => $this->get_base_url() . '/images/icon.png',
		);
	}

	return $services;
}

Intercept the Notification

The gform_pre_send_email filter is used to intercept the notification email, pass the email to the new service, and then prevent WordPress and other add-ons from also sending the email.

/**
 * If the notification "Email Service" setting is a match prepare to send the email.
 *
 * @param array $email The email properties.
 * @param string $message_format The message format, html, or text.
 * @param array $notification The Notification object which produced the current email.
 *
 * @return array
 */
public function maybe_send_email( $email, $message_format, $notification ) {

	// If the notification is not assigned to this service or the service API is not initialized, return the email.
	if ( rgar( $notification, 'service' ) !== 'the_service_name' || ! $this->initialize_api() ) {
		return $email;
	}

	// If the email has already been aborted, return the email.
	if ( $email['abort_email'] ) {
		$this->log_debug( __METHOD__ . '(): Not sending email because the notification has already been aborted by another Add-On.' );

		return $email;
	}

	$result = $this->send_email( $email, $message_format, $notification );

	if ( $result ) {
		// The service successfully sent the email; prevent WordPress and other add-ons from also sending the email.
		$email['abort_email'] = true;
	}

	return $email;
}

Send the Email

Now we know that no other add-ons have already aborted the email and that this service was selected for the notification the email can be processed and passed to the service for delivery.

/**
 * Send the email via the new service.
 *
 * @param array $email The email properties.
 * @param string $message_format The message format, html, or text.
 * @param array $notification The Notification object which produced the current email.
 *
 * @return bool
 */
public function send_email( $email, $message_format, $notification ) {

	// pass the email to the service

	return $result;
}