This is even the case if your web application knows exactly who that person is. When they log into a customer portal, complete a chatbot conversation, or book a demo, you have their email (or some other sort of identifier). Mautic doesn't.
The Mautic Identity Sync plugin by Leuchtfeuer bridges this gap. At the moment your application identifies a user, it can tell Mautic, and Mautic will now connect all further action to the known contact (instead of an anonymous one). It will even create that contact if it doesn't exist yet, or enhance the preexisting one if additional data is provided.
One URL call is all it takes
As soon as your application knows who a user is, fire a request to mcontrol.gif with their identifier:
https://your-mautic.site/mcontrol.gif?email=customer@example.com
That's it. Mautic identifies the corresponding contact and associates the current browser activity with that contact. Here, email is the identifier - the field Mautic uses to look up and match the contact.
Contact data can optionally be updated at the same time. This is done by passing additional parameters in the same call, for example the first name:
https://your-mautic.site/mcontrol.gif?email=customer@example.com&firstname=Anna
Unlike email, firstname here plays no role in identifying the contact. It's simply written to the record once the contact has been matched.
If a secondary identifier is configured (see Mautic-side setup below), it must be passed as its own parameter as well, and is checked alongside the (primary) identifier before the contact is treated as identified:
The primary identifier does not have to be an email address. Any field marked as "Is Unique Identifier" in Mautic can be used.
Where to use it
The most common use case is a login page where you can fire mcontrol.gif right after successful authentication. But the same approach works anywhere your application captures a verified identifier outside of a Mautic form:
- A chatbot that collects an email early in the conversation
- A demo or appointment booking confirmation page
- Any other lead generation touchpoint using a third-party tool
Mautic-side setup
Go to Settings → Plugins → Identity Sync.
Primary Identifier (required): Select the contact field you use for identification. Only fields marked as "Is Unique Identifier" appear here. The field must also be set to "Publicly updatable". Otherwise the plugin cannot perform the lookup and will create a new anonymous contact instead.
Secondary Identifier (optional): If configured, the second field must also match before a contact is identified. This is recommended for any production setup: since the mcontrol.gif URL is visible in your page source, a secondary identifier (e.g. a customer number) ensures that knowing an email address alone is not enough to trigger an identification. It also prevents accidental mis-identification if two contacts share the same primary identifier.
Generating the URL in your CMS
The integration is based on a clear pixel "mcontrol.gif" (just like a tracking pixel) which is fetched after successful login or other identification.
The identifying application (e.g. CMS) will have to add the proper parameters to the URL.
Here are two examples for doing that.
WordPress
<?php
$current_user = wp_get_current_user();
if ( is_user_logged_in() && !empty($current_user->user_email) ) {
echo '<img src="https://your-mautic.site/mcontrol.gif?email=' . urlencode($current_user->user_email) . '" alt="" width="1" height="1">';
}
?>
TYPO3
<f:if condition="{f:security.ifAuthenticated()}">
<f:variable name="user" value="{f:security.currentUser()}" />
<img src="https://your-mautic.site/mcontrol.gif?email={user.email}" alt="" width="1" height="1" />
</f:if>
For any other CMS or custom application: fire a GET request to mcontrol.gif with the identifier as a parameter, but only after successful authentication.
Behind the scenes
When mcontrol.gif fires, the plugin checks the current browser session and runs through the following logic:
No session yet: looks up the contact by the identifier passed in the URL. If found, the session is connected to that contact and any additional fields passed are updated. If no contact is found, a new one is created.
Session exists and already belongs to the right contact: the plugin just updates any additional fields passed in the URL. Nothing else changes.
Session exists but belongs to a different (anonymous) contact: the plugin finds the matching contact and reassigns the session to them. All subsequent actions are now attributed to the correct person. If no matching contact exists, a new one is created.
This last scenario is where mcontrol.gif fundamentally differs from mtracking.gif, Mautic's built-in tracking pixel. It tracks page visits but cannot process the given identity from the login or other forms of authentication nor match it to an existing contact.
mcontrol.gif is built specifically to do what mtracking.gif cannot: actively look up a known identity and connect the session to the right person, regardless of what was tracked before
Best practices and Troubleshooting
- Fire the pixel only after a successful login or other authentication, not on every page load.
- Make sure the identifier field is set to "Is Unique Identifier" and "Publicly updatable", if identity sync is not working, check this first.
- Use the secondary identifier in any production setup to protect against spoofing and accidental mis-identification.
- Test with a cleared session or private browser window to verify the sync is working correctly.
Link to GitHub: https://github.com/Leuchtfeuer/mautic-identity-sync