suredonation_email_smart_tag_groups Filter Hook

Overview

The suredonation_email_smart_tag_groups filter allows developers to customize the smart tag groups displayed in the SureDonation email notification editor.

These groups control which smart tags administrators can see and insert from the email editor’s tag picker.

If you add a custom smart tag using suredonation_email_smart_tags, you should also register that tag here. Otherwise, the tag may work when manually added to an email template but will not appear in the editor.

When to Use This Filter

Use this filter when you need to:

• Add custom smart tags to the email editor.
• Create a new group of related smart tags.
• Add custom integration or CRM tags.
• Change the labels displayed for smart tags.
• Make custom tags available through the email editor’s tag picker.

Filter Signature

apply_filters( 'suredonation_email_smart_tag_groups', $smart_tags['email_grouped']);

apply_filters( 'suredonation_email_smart_tag_groups', $smart_tags['email_grouped']);

Parameters

Each group contains a title and a list of tags.

Group Structure

[
[
'title' => 'Group Name',
'tags'  => [
[
'tag'   => '{example_tag}',
'title' => 'Example Tag',
],
],
],
]

[
[
'title' => 'Group Name',
'tags'  => [
[
'tag'   => '{example_tag}',
'title' => 'Example Tag',
],
],
],
]

Tag Properties

Return Value

Return the modified array of smart tag groups.

return $groups;

return $groups;

If the callback returns a non-array value, SureDonation discards the result and uses the original list.

Groups must also contain a valid tags array. Invalid group structures are discarded.

Basic Usage

add_filter( 'suredonation_email_smart_tag_groups', 'your_custom_function', 10, 1);

function your_custom_function( $groups ) {

// Add or modify smart tag groups.

return $groups;

}

add_filter( 'suredonation_email_smart_tag_groups', 'your_custom_function', 10, 1);

function your_custom_function( $groups ) {

// Add or modify smart tag groups.

return $groups;

}

Example: Add a Custom CRM Group

The following example adds a new CRM group containing a {crm_contact_id} smart tag.

add_filter( 'suredonation_email_smart_tag_groups', 'mysite_add_smart_tag_group', 10, 1);

function mysite_add_smart_tag_group( $groups ) {

$groups[] = [

'title' => 'CRM',

'tags'  => [

[

'tag'   => '{crm_contact_id}',

'title' => 'CRM Contact ID',

],

],

];

return $groups;

}

add_filter( 'suredonation_email_smart_tag_groups', 'mysite_add_smart_tag_group', 10, 1);

function mysite_add_smart_tag_group( $groups ) {

$groups[] = [

'title' => 'CRM',

'tags'  => [

[

'tag'   => '{crm_contact_id}',

'title' => 'CRM Contact ID',

],

],

];

return $groups;

}

The new tag will appear in the email editor under the CRM group.

Register the Tag Resolver

Adding a tag to the editor does not define its replacement value.

You must also register a resolver using: suredonation_email_smart_tags

For example:

add_filter( 'suredonation_email_smart_tags', 'mysite_resolve_crm_tag', 10, 2);

function mysite_resolve_crm_tag( $tags, $donation_data ) {

$tags['{crm_contact_id}'] = '12345';

return $tags;

}

add_filter( 'suredonation_email_smart_tags', 'mysite_resolve_crm_tag', 10, 2);

function mysite_resolve_crm_tag( $tags, $donation_data ) {

$tags['{crm_contact_id}'] = '12345';

return $tags;

}

The two filters work together:

suredonation_email_smart_tag_groups

              ↓

Shows the tag in the editor

              ↓

Administrator inserts the tag

              ↓

suredonation_email_smart_tags

              ↓

Resolves the tag value

              ↓

Email is sent

Example: Add Multiple Tags

You can add several related tags to the same group.

add_filter( 'suredonation_email_smart_tag_groups', 'mysite_add_crm_tags', 10, 1);

function mysite_add_crm_tags( $groups ) {

$groups[] = [

'title' => 'CRM',

'tags'  => [

[

'tag'   => '{crm_contact_id}',

'title' => 'CRM Contact ID',

],

[

'tag'   => '{crm_account_id}',

'title' => 'CRM Account ID',

],

],

];

return $groups;

}

add_filter( 'suredonation_email_smart_tag_groups', 'mysite_add_crm_tags', 10, 1);

function mysite_add_crm_tags( $groups ) {

$groups[] = [

'title' => 'CRM',

'tags'  => [

[

'tag'   => '{crm_contact_id}',

'title' => 'CRM Contact ID',

],

[

'tag'   => '{crm_account_id}',

'title' => 'CRM Account ID',

],

],

];

return $groups;

}

Smart Tag Groups and Resolvers

It is recommended to register both sides of a custom smart tag.

1. Add the tag to the editor

Use: suredonation_email_smart_tag_groups

2. Define the replacement value

Use: suredonation_email_smart_tags

Registering only the resolver means the tag can be processed at send time but will not be available in the editor’s tag picker.

Registering only the group means the tag appears in the editor but does not have a replacement value when the email is rendered.

Subscription Smart Tags

SureDonation handles subscription-related tags separately.

The following tags are added to the first smart tag group when SureDonation Pro is active:

{subscription_id}
{subscription_interval}

{subscription_id}
{subscription_interval}

These tags are kept in the Free plugin so that the Free and Pro versions can work together without requiring a matching Pro release for these specific tags.

Additional subscription-related functionality can be provided by Pro through this filter.

Related Hooks

• suredonation_email_smart_tags: Filters the smart tag replacement values used when rendering emails.
• suredonation_default_email_notifications: Filters the default email notification configuration.
• suredonation_email_sent: Fires after a SureDonation email is sent.