Tracking user data

POST https://api.sidemail.io/v1/contacts

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.

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. Sidemail supports these data types:

Naming convention

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

  • Full name

  • fullName

  • FullName

  • full_name

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

Using contacts API

Request method and URL

Create or update contact that represents a user in your system by making a POST HTTP request:

POST https://api.sidemail.io/v1/contacts

Example request

This is how a typical contacts request should look like:

Generic example
Node.js SDK
Node.js (node-fetch)
POST https://api.sidemail.io/v1/contacts
Authorization: Bearer xxxxxxxxxxxx
Content-Type: application/json
{
"emailAddress": "john.doe@example.com",
"identifier": "123",
"customProps": {
"Full name": "John doe",
"Pricing plan": "premium",
"Registered at": "2019-08-15T13:20:39.160Z",
"Last seen at": "2019-08-20T17:40:39.160Z"
}
}
/**
* Require the Sidemail library.
*
* If you haven't already, install it with either:
* - npm install @sidemail/sdk-js
* - yarn @sidemail/sdk-js
**/
const configureSidemail = require("@sidemail/sdk-js");
// Create Sidemail instance and set your API key.
const sidemail = configureSidemail({
apiKey: "xxxxx",
});
try {
const response = await sidemail.performApiRequest("contacts", {
emailAddress: "john.doe@example.com",
identifier: "123",
customProps: {
"Full name": "John doe",
"Pricing plan": "premium",
"Registered at": "2019-08-15T13:20:39.160Z",
"Last seen at": "2019-08-20T17:40:39.160Z",
},
});
// Response will contain either "created" or "updated" status
console.log(`User was successfully: '${response.staus}'`);
} catch (err) {
// Uh-oh, we have an error! You error handling logic...
console.error(err);
}
const fetch = require("node-fetch");
const response = await fetch("https://api.sidemail.io/v1/contacts", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer xxxxxxxxxxxx",
},
body: JSON.stringify({
emailAddress: "john.doe@example.com",
identifier: "123",
customProps: {
"Full name": "John doe",
"Pricing plan": "premium",
"Registered at": "2019-08-15T13:20:39.160Z",
"Last seen at": "2019-08-20T17:40:39.160Z"
}
}),
});
if (!response.ok) {
throw new Error("Error sending user data to Sidemail");
}

TIP: You can get the request example above with your real API key and all available contact properties that you can track in pre-generated JSON. Go to your project → contacts page → click import contacts → click view api code example and there you go! 🤩

Responses

  • If contact was newly created, Sidemail will respond with 201 Created.

  • If contact was updated, Sidemail will respond with 202 Accepted.

  • If there was validation error or any other error while processing the request, Sidemail will respond with a typical error structure, as described in API Responses.

Available JSON body parameters:

Key

Type

Description

identifier

string

Unique string, that represent user in your system. It's recommended to use identifier and not just rely on email.

emailAddress

string

User's email address. If user changes email in your system, Sidemail will update the email value only if identifier was set. Otherwise, new contact will be created.

isSubscribed

boolean

Specifies if Sidemail should set contact's status to subscribed or unsubscribed.

customProps

object

Specify values of properties here. Use exactly the same property key name (whitespace sensitive) as you used when creating the property.

Property value has to have matching data type as you specified when creating the property. Otherwise, Sidemail returns validation error. Null is allowed.