Give 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 donation receipts and admin donation notifications.

The give_add_email_tag() function takes three parameters:

  • $tag – The tag to register, such as “admin_email”. In the Give email settings, tags are wrapped with {} but not when they are registered.
  • $description – A description of what the tag displays.
  • $func – The callback function to render the tag’s output.

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.

Here’s an example that shows how to add a tag that displays a custom field.

/**
 * Adds a Custom "Referral" Tag
 * @description: This function creates a custom Give email template tag
 *
 * @param $payment_id
 */
function my_custom_prefix_add_sample_referral_tag( $payment_id ) {
	give_add_email_tag( 'referral', 'This tag can be used to output the custom referral field', 'my_custom_prefix_get_donation_referral_data' );
}

add_action( 'give_add_email_tags', 'my_custom_prefix_add_sample_referral_tag' );

/**
 * Get Donation Referral Data 
 * 
 * @description Example function that returns Custom field data if present in payment_meta; the example used here is in conjunction with the Give documentation tutorials
 * @param $payment_id
 *
 * @return string|void
 */
function my_custom_prefix_get_donation_referral_data( $payment_id ) {

	$payment_meta = give_get_payment_meta( $payment_id );
	$output       = __( 'No referral data found.', 'give' );
	if ( isset( $payment_meta['referral'] ) && ! empty( $payment_meta['referral'] ) ) {
		$output = $payment_meta['referral'];
	}

	return $output;
}

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

give-custom-email-tag

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

Note: The $payment ID is passed to the callback function as a parameter, allowing you to look up any related data that is needed.

Creating Individual Email Tags for Use with Form Field Manager

Our Form Field Manager Add-on gives you a UI to add custom fields to your Give form. Currently it has only one email tag: {all_custom_fields}. If you want to have more fine-tuned control over your email tags with your custom fields generated from Form Field Manager then you can do that with some minor adjustments to the code above.

In the code examples above, you’ll see that we’re adding the custom field data to the payment meta. Form Field Manager doesn’t do that. Instead it adds the custom field data to the Post Meta of the Transaction (Give Transactions are a hidden Custom Post Type). So here’s how you’d have to add the data to the email tag instead:

Add Form Field Manager Data to your Custom Email Tag

/**
 * Get Donation Referral Data 
 * 
 * @description Example function that returns Custom field data if present in payment_meta; the example used here is in conjunction with the Give documentation tutorials
 * @param $payment_id
 *
 * @return string|void
 */

function my_custom_prefix_get_donation_referral_data( $payment_id ) {

	$payment_meta = get_post_meta($payment_id);
	$output       = __( 'No referral data found.', 'give' );

	if ( isset( $payment_meta['referral'] ) && ! empty( $payment_meta['referral'] ) ) {
		$output = $postmeta['referral'][0];
	}

	return $output;
}