How to Programmatically Create FluentCRM Smart Links

FluentCRM’s Smart Links are powerful tools that allow you to trigger specific actions when subscribers click on links in your emails. These actions can include adding or removing tags, subscribing users to lists, or even automatically logging them into your WordPress site. However, creating smart links manually through the FluentCRM interface can be time-consuming, especially if you need to generate many links or integrate them into your custom workflows.

This tutorial shows you how to programmatically create FluentCRM smart links using PHP, giving you complete control over the process and enabling automation of your email marketing workflows.

What Are FluentCRM Smart Links?

Smart links in FluentCRM are special URLs that perform actions on your subscribers when clicked. Instead of just redirecting users to a page, they can:

• Add specific tags to the subscriber
• Subscribe users to particular lists
• Remove tags or unsubscribe from lists
• Automatically log users into your WordPress site
• Track engagement and user behaviour

This makes them incredibly useful for creating interactive email campaigns, user onboarding sequences, and personalised content experiences.

Why Create Smart Links Programmatically?

Creating smart links through code offers several advantages:

• Automation: Generate links automatically based on user actions or data
• Bulk creation: Create hundreds of personalised links quickly
• Integration: Seamlessly integrate with your existing WordPress workflows
• Consistency: Ensure all links follow the same format and rules
• Dynamic content: Create links that adapt to different user segments

Step-by-Step Implementation

Step 1: Create the Helper Function

The first step is to create a reusable function that handles the smart link creation process. This function will use FluentCRM’s SmartLink model to interact directly with the database.

Add the code below to your theme’s functions.php file or a custom plugin:

		/**
 * Create a smart link using the model.
 *
 * @param string $title The title of the smart link.
 * @param string $target_url The target URL of the smart link.
 * @param array  $options The options for the smart link.
 * @return object|WP_Error The created smart link or WP_Error if it failed.
 */
function tct_create_smart_link( $title, $target_url, $options = array() ) {
	// Validate required inputs
	if ( empty( $title ) || empty( $target_url ) ) {
		return new WP_Error( 'invalid_input', 'Title and target URL are required.' );
	}

	// Validate URL format
	if ( ! filter_var( $target_url, FILTER_VALIDATE_URL ) ) {
		return new WP_Error( 'invalid_url', 'Target URL is not valid.' );
	}

	// Ensure the model class exists
	if ( ! class_exists( 'FluentCampaign\App\Models\SmartLink' ) ) {
		return new WP_Error( 'missing_class', 'FluentCRM SmartLink model not found.' );
	}

	// Default options
	$defaults = array(
		'tags'         => array(),
		'lists'        => array(),
		'remove_tags'  => array(),
		'remove_lists' => array(),
		'auto_login'   => 'no',
		'notes'        => '',
	);

	$options = wp_parse_args( $options, $defaults );

	// Sanitise and escape inputs
	$title = esc_html( sanitize_text_field( $title ) );
	$target_url = esc_url_raw( $target_url );
	$notes = sanitize_textarea_field( $options['notes'] );

	// Validate and ensure array options contain only positive integers
	foreach ( array( 'tags', 'lists', 'remove_tags', 'remove_lists' ) as $key ) {
		if ( ! is_array( $options[ $key ] ) ) {
			$options[ $key ] = array();
		}
		// Filter out non-numeric values and convert to integers
		$options[ $key ] = array_map( 'intval', array_filter( $options[ $key ], 'is_numeric' ) );
		// Remove any zero or negative values
		$options[ $key ] = array_filter( $options[ $key ], function( $value ) {
			return $value > 0;
		});
		// Reindex array
		$options[ $key ] = array_values( $options[ $key ] );
	}

	// Validate auto_login option
	$auto_login = in_array( $options['auto_login'], array( 'yes', 'no' ), true ) ? $options['auto_login'] : 'no';

	// Prepare the actions array
	$actions = array(
		'auto_login'   => $auto_login,
		'tags'         => $options['tags'],
		'lists'        => $options['lists'],
		'remove_tags'  => $options['remove_tags'],
		'remove_lists' => $options['remove_lists'],
	);

	try {
		// Create the smart link using the model
		$smart_link = \FluentCampaign\App\Models\SmartLink::create(
			array(
				'title'      => $title,
				'target_url' => $target_url,
				'notes'      => $notes,
				'actions'    => $actions,
			)
		);

		return $smart_link;
	} catch ( Exception $e ) {
		return new WP_Error( 'creation_failed', 'Failed to create smart link: ' . $e->getMessage() );
	}
}
					

				Copy
				
									
			
			

Step 2: Understanding the Function Parameters

Let’s break down what each parameter does:

• $title: A descriptive name for your smart link (for internal reference)
• $target_url: The final destination URL where users will be redirected
• $options: An array of actions and settings for the smart link

The options array supports these parameters:

• tags: Array of tag IDs to add to the subscriber
• lists: Array of list IDs to subscribe the user to
• remove_tags: Array of tag IDs to remove from the subscriber
• remove_lists: Array of list IDs to unsubscribe the user from
• auto_login: ‘yes’ or ‘no’ – whether to automatically log in the user
• notes: Internal notes about the smart link

Step 3: Basic Usage Example

Here’s how to use the function to create a simple smart link:

		$smart_link = tct_create_smart_link(
		'My Custom Link',
		'https://example.com/target-page',
		array(
			'notes'        => 'Created using SmartLink model',
			'tags'         => array( 1, 2 ),
			'lists'        => array( 1, 2 ),
			'remove_tags'  => array( 3 ),
			'remove_lists' => array( 4 ),
			'auto_login'   => 'yes',
		)
	);
					

				Copy
				
									
			
			

This example creates a smart link that:

• Adds tags with IDs 1 and 2 to the subscriber
• Subscribes the user to lists 1 and 2
• Removes tag with ID 3
• Unsubscribes from list 4
• Automatically logs in the user
• Redirects to https://example.com/target-page

Code Breakdown

Let’s examine the key parts of our function:

Safety Check

		// Ensure the model class exists.
if ( ! class_exists( 'FluentCampaign\App\Models\SmartLink' ) ) {
    return false;
}
					

				Copy
				
									
			
			

This check ensures FluentCRM is active and the SmartLink model is available before attempting to create links.

Default Options

		$defaults = array(
    'tags'         => array(),
    'lists'        => array(),
    'remove_tags'  => array(),
    'remove_lists' => array(),
    'auto_login'   => 'no',
    'notes'        => '',
);

$options = wp_parse_args( $options, $defaults );
					

				Copy
				
									
			
			

We define sensible defaults for all options, then merge them with any provided options using wp_parse_args().

Actions Array

		$actions = array(
    'auto_login'   => $options['auto_login'],
    'tags'         => $options['tags'],
    'lists'        => $options['lists'],
    'remove_tags'  => $options['remove_tags'],
    'remove_lists' => $options['remove_lists'],
);
					

				Copy
				
									
			
			

The actions array contains all the behaviours that will be triggered when someone clicks the smart link. FluentCRM automatically serialises this data for storage.

Conclusion

Creating FluentCRM smart links programmatically opens up powerful possibilities for automating your email marketing workflows. Whether you’re building custom integrations, creating personalised user journeys, or simply want to streamline your link management process, this approach gives you complete control over your smart links.

The function we’ve created is flexible enough to handle most use cases whilst being simple enough to understand and modify. Remember to always test your implementation thoroughly and consider the user experience when designing your smart link workflows.