Introduction

Tracking user (contact) data is useful to learn more about your users, and makes possible sending targeted emails. For example, you can track when user was last seen, how many todos completed (if todos app) or the favourite color. You can track anything, really. The more you know about your user, the better you can target them with specific emails.

What data you should track?

To get your some ideas for what data you could track about your users:

• Generic – name, company, website, registration date

• Payment – plan type, trial expiration date, billing interval, next billing date, customer lifetime value

• Activity – last seen date; your application specifics, if todos app: todos created, todos archived, last todo created at date, onboarding completed date

Setting up contact properties

Create contact (user) properties

Before you can track any user data, you need to tell Sidemail what data should expect. Head over to your project settings and find the Contact properties section. There, you can create and edit properties that you track about your users.

Supported data types:

• String
• Number
• Date ISO 8601

Naming convention

You can name contact properties in whatever naming convention you prefer. For example, this how you could name full name property:

• fullName
• FullName
• full_name
• Full name

Example

Push contact data to Sidemail via create or update contact method using the Node.js library.

const configureSidemail = require("sidemail");
const sidemail = configureSidemail({ apiKey: "xxxxx" });
  
const response = await sidemail.contacts.createOrUpdate({
	emailAddress: "john.doe@example.com",
	identifier: "123", // ID representing the user in your database
	customProps: {
		fullName: "John doe",
		pricingPlan: "premium",
		registeredAt: "2019-08-15T13:20:39.160Z",
		lastSeenAt: "2019-08-20T17:40:39.160Z",
		// ... more of your contact data ...
	},
});

Force-triggering automation

If you need to force trigger an automation so that all contacts currently in a matching state enter it, follow these steps:

• Create a temporary custom contact property (e.g., name trigger and type number). Ensure this new property is not used in any other automation to avoid unintended re-triggers.
• Go to the automation you want to force trigger, click update, and add this property as one of the triggers (e.g., trigger equals 1). Save the changes.
• Use the Sidemail.io API to get all contacts and update each contact with the property trigger set to 1. Since your automation will have other triggers, it’s safe to update all contacts; only the correct contacts based on the automation’s triggers will enter the automation.
• As a cleanup step, after you remove trigger as the automation trigger, make a second API update request to set the trigger property to null.

This process ensures that only the relevant contacts will enter the automation while maintaining the integrity of other automations. Here's a code example:

const configureSidemail = require("sidemail");
const sidemail = configureSidemail({ apiKey: "xxxxx" });
  
async function updateContact(contact) {
    await sidemail.contacts.createOrUpdate({
        emailAddress: contact.emailAddress,
        customProps: { trigger: 1 },
    });
}

async function processAllContacts() {
    let paginationCursorNext = null;
    let hasMore = true;
    let totalUpdated = 0;

    while (hasMore) {
        const response = await sidemail.contacts.list({ paginationCursorNext });

        for (const contact of response.data) {
            console.log(`Updating: ${contact.emailAddress} (${++totalUpdated})`);
            await updateContact(contact);
        }

        paginationCursorNext = response.paginationCursorNext;
        hasMore = response.hasMore;
    }

    console.log("All contacts processed.");
}

processAllContacts();