In the world of targeted marketing and personalized user experiences, effective user segmentation is king. The ability to group users based on their behavior, status, or demographics allows you to deliver the right message at the right time. But as your user base grows from hundreds to millions, the simple act of managing and comparing lists becomes a significant engineering challenge. Running these data manipulation tasks on your own servers can lead to performance bottlenecks, complex code, and a maintenance nightmare.
This is where lists.do comes in. As a "Lists as a Service" platform, it provides powerful, scalable, and developer-first API endpoints for all your list management needs. You can offload complex sorting, filtering, and set theory operations to our optimized infrastructure, allowing you to focus on your application's core logic.
In this tutorial, we'll walk through a practical example: building a real-time user segmentation engine for a marketing automation workflow using the lists.do API.
Imagine you run a SaaS application with a free trial. Your goal is to increase conversions from trial to paid. The perfect audience for a "last chance" discount offer is users who are currently in their trial but have not yet converted to a paid plan.
In your database, you might have these user groups as separate lists of email addresses or user IDs:
To find your target segment, you need to calculate the difference between activeTrialUsers and paidSubscribers. Let's see how trivially simple this is with lists.do.
First, you'll need to install the official SDK and initialize the client with your API key.
import { createClient } from '@do/sdk';
// Initialize the client. You can get your API key from the lists.do dashboard.
const lists = createClient('your-api-key-here');
The core of our segmentation engine is a single API call. We'll use the diff endpoint, which is designed for exactly this type of set theory operation. It takes a source list and an exclude list and returns only the items that exist in source but not in exclude.
Let's put it into practice.
// Sample data from our application's database
const activeTrialUsers = [
'user1@example.com', // Hasn't converted yet
'user2@example.com', // Recently converted
'user4@example.com' // Still in trial
];
const paidSubscribers = [
'user2@example.com',
'user3@example.com' // Was an old trial user, now paid
];
// The function to find our target segment
async function findTrialUsersToNurture() {
console.log("Finding trial users who have not yet converted...");
const { data, error } = await lists.diff({
source: activeTrialUsers,
exclude: paidSubscribers
});
if (error) {
console.error("API Error:", error.message);
return;
}
console.log("Target segment for marketing campaign:", data);
// Output: Target segment for marketing campaign: ['user1@example.com', 'user4@example.com']
return data;
}
findTrialUsersToNurture();
Just like that, you have your perfectly segmented list! No more writing convoluted loops, handling edge cases, or worrying about performance. You can now pass this resulting list of emails directly to your marketing email provider.
What if you wanted to create an even more refined segment? For instance, let's identify users for a re-engagement campaign: users who are paid subscribers but have not logged in recently.
You'd have two lists:
The logic is the same—we just need another diff operation.
const paidSubscribers = ['user2@example.com', 'user3@example.com', 'user5@example.com'];
const recentLogins = ['user1@example.com', 'user2@example.com'];
async function findInactiveSubscribers() {
const { data } = await lists.diff({
source: paidSubscribers,
exclude: recentLogins
});
console.log("Inactive subscribers to re-engage:", data);
// Output: Inactive subscribers to re-engage: ['user3@example.com', 'user5@example.com']
}
By combining diff, intersect, filter, and other array operations from the API, you can build incredibly sophisticated workflows with minimal code.
You could build this logic yourself, but lists.do offers compelling advantages:
Ready to supercharge your application's data manipulation capabilities? Get started with lists.do today and turn complex list operations into a single API call.
Why would I use an API for list operations?
Using lists.do abstracts away the complexity of common data manipulation tasks. It allows you to reduce boilerplate code, ensure high performance on large datasets, and focus on your application's core business logic.
What types of list operations can I perform?
Our platform supports a comprehensive suite of operations, including sorting, filtering, mapping, finding unique items (uniques), calculating intersections and differences (diffs), merging, and other powerful set theory functions.
How does lists.do handle very large lists?
lists.do is built for scale. Operations are executed on our optimized cloud infrastructure, allowing you to process lists with millions of items asynchronously without impacting your own server resources.
Can I integrate lists.do with my current tech stack?
Yes. We offer simple REST APIs and developer-friendly SDKs for languages like TypeScript/JavaScript, Python, and Go, making it easy to integrate list operations into any new or existing project.