How to Add Custom Email Tags

GiveWP allows you to create custom email tags that can be used to add selected data to your email message. This is useful if you have created custom fields or want to send other data from the database.

Introducing give_add_email_tag()

The give_add_email_tag() function allows you to register custom email tags for donor and admin notifications.

As of 2.2.1+ the give_add_email_tag() function takes an array of arguments to create an email tag:

• tag – The name of the tag to register, such as “engraving_message” as in our code example below. In the GiveWP email settings, tags are wrapped with {} but not when they are registered.
• desc – A description of what the tag displays. This is informational for admins so they know what to expect the tag outputs in the notification.
• func – The callback function to render the tag’s output.
• context – The emails that this tag should appear as functional underneath the content editor. Options include:
  • donation – appears on donation related emails
  • form – information related to the donation form.
  • donor – information related to the donor. Appears on donor emails.
  • general – appears on all emails
• is_admin – Whether this tag should only be available to admins. Usually reserved for tags with sensitive information. Default is false.

Now that we’ve reviewed the key function in creating custom email tags, let’s see how we can apply this to the custom field created in our “how to create custom form fields” article.

/**
 * Adds a Custom "Engraved Message" Tag
 *
 * This function creates a custom GiveWP email template tag.
 */
function my_custom_prefix_add_sample_referral_tag() {
	give_add_email_tag(
		array(
			'tag'      => 'engraving_message', // The tag name.
			'desc'     => __( 'This outputs the Engraved Message', 'give' ), // For admins.
			'func'     => 'my_custom_prefix_get_donation_engraving_info', // Callback to function below.
			'context'  => 'general', // This tag can be for both admin and donor notifications.
			'is_admin' => false, // default is false. This is here to simply display it as an option.
		)
	);
}

add_action( 'give_add_email_tags', 'my_custom_prefix_add_sample_referral_tag' );

/**
 * Get Custom Engraving Message
 *
 * Example function that returns custom field data if present in payment_meta;
 * The example used here is in conjunction with the GiveWP documentation tutorials.
 *
 * @param array $tag_args Array of arguments
 *
 * @return string
 */
function my_custom_prefix_get_donation_engraving_info( $tag_args ) {

	// Update get meta request to get your custom data. You can pull from payment meta, donor meta, or other custom meta.
	$engraving_message = give_get_meta( $tag_args['payment_id'], 'give_engraving_message', true );
	$output            = __( 'No engraving message :(', 'give' ); // Fallback message. (optional)
	
	if ( ! empty( $engraving_message ) ) {
		$output = wp_kses_post( $engraving_message );
	}

	return $output;
}

The code above will create a custom template tag that you can then add to your emails.

With the example above active, you could use {engraving_message} in your donation receipt and notifications to display the custom field data.