suredonation_email_smart_tags Filter Hook

Overview

The suredonation_email_smart_tags filter allows developers to customize the smart tags available in SureDonation notification emails.

You can use this filter to:

• Add custom smart tags.
• Modify the value of an existing smart tag.
• Use donation or campaign data to generate dynamic email content.
• Add custom values that can be used in email subjects, bodies, and sender fields.

For example, you can add a {donor_first_name} tag and use it in any supported email notification template.

When to Use This Filter

Use this filter when you need to:

• Add custom information to donation emails.
• Create custom smart tags.
• Modify the value of an existing core smart tag.
• Personalize notification emails using donation or campaign data.
• Reuse dynamic values across multiple email templates.

Filter Signature

apply_filters( 'suredonation_email_smart_tags', $tags, $donation_data, $campaign );

apply_filters( 'suredonation_email_smart_tags', $tags, $donation_data, $campaign );

Parameters

Core Smart Tags

SureDonation provides several built-in smart tags, including:

Return Value

Return the modified $tags array.

return $tags;

return $tags;

You can add new smart tags:

$tags['{donor_first_name}'] = 'John';
return $tags;

$tags['{donor_first_name}'] = 'John';
return $tags;

New keys that are not part of the core smart-tag set are automatically escaped with esc_html() after the filter runs.

This helps protect custom values from introducing unsafe HTML into email content.

Basic Usage

add_filter( 'suredonation_email_smart_tags', 'your_custom_function', 10, 3 );

function your_custom_function( $tags, $donation_data, $campaign ) {

// Add or modify smart tags here.

return $tags;

}

add_filter( 'suredonation_email_smart_tags', 'your_custom_function', 10, 3 );

function your_custom_function( $tags, $donation_data, $campaign ) {

// Add or modify smart tags here.

return $tags;

}

Example: Add a Donor First Name Tag

The following example creates a {donor_first_name} smart tag from the donor’s full name.

add_filter( 'suredonation_email_smart_tags', 'mysite_add_first_name_tag', 10,3);

function mysite_add_first_name_tag(

$tags,

$donation_data,

$campaign

) {

$name = $donation_data['donor_name'] ?? '';

$tags['{donor_first_name}'] = explode( ' ', $name )[0];

return $tags;

}

add_filter( 'suredonation_email_smart_tags', 'mysite_add_first_name_tag', 10,3);

function mysite_add_first_name_tag(

$tags,

$donation_data,

$campaign

) {

$name = $donation_data['donor_name'] ?? '';

$tags['{donor_first_name}'] = explode( ' ', $name )[0];

return $tags;

}

You can then use the tag in an email notification:

Hello {donor_first_name},

Hello {donor_first_name},

Thank you for supporting our campaign.

When the email is generated, SureDonation replaces the tag with the corresponding value.

Example: Add a Custom Campaign Tag

You can also use the campaign object to create custom campaign-related tags.

add_filter( 'suredonation_email_smart_tags', 'mysite_add_campaign_id_tag', 10, 3 );

function mysite_add_campaign_id_tag(

$tags,

$donation_data,

$campaign

) {

$tags['{campaign_id}'] = (string) $campaign->ID;

return $tags;

}

add_filter( 'suredonation_email_smart_tags', 'mysite_add_campaign_id_tag', 10, 3 );

function mysite_add_campaign_id_tag(

$tags,

$donation_data,

$campaign

) {

$tags['{campaign_id}'] = (string) $campaign->ID;

return $tags;

}

You can then use:

Campaign ID: {campaign_id}

Campaign ID: {campaign_id}

in the email template.

Example: Modify an Existing Smart Tag

You can modify a value that SureDonation already provides.

add_filter( 'suredonation_email_smart_tags', 'mysite_customize_campaign_name', 10, 3 );

function mysite_customize_campaign_name(

$tags,

$donation_data,

$campaign

) {

$tags['{campaign_name}'] = 'Support: ' . $tags['{campaign_name}'];

return $tags;

}

add_filter( 'suredonation_email_smart_tags', 'mysite_customize_campaign_name', 10, 3 );

function mysite_customize_campaign_name(

$tags,

$donation_data,

$campaign

) {

$tags['{campaign_name}'] = 'Support: ' . $tags['{campaign_name}'];

return $tags;

}

This changes the replacement value used for {campaign_name }.

Smart Tag Processing Flow

The filter runs while SureDonation prepares the email content:

Donation Data

      ↓

Campaign Data

      ↓

Build Core Smart Tags

      ↓

suredonation_email_smart_tags

      ↓

Add or Modify Smart Tags

      ↓

Replace Tags in Email

      ↓

Send Notification

Security Considerations

When adding custom smart tags, make sure the values are appropriate for email output.

New smart-tag keys are automatically escaped using: esc_html()

after the filter runs.

Avoid intentionally inserting untrusted HTML into custom smart-tag values.

For example, prefer:

$tags['{donor_code}'] = sanitize_text_field( $code );

$tags['{donor_code}'] = sanitize_text_field( $code );

over directly passing untrusted user input.

Related Hooks

• Suredonation_email_sent: Fires after a SureDonation email has been sent.
• Suredonation_default_email_notifications: Filters the default email notification configuration.