Integrate contact profiles


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:

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

Create or update contact via API

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


Example request

This is how a typical contacts request should look like:

Authorization: Bearer xxxxxxxxxxxx
Content-Type: application/json
  "emailAddress": "",
  "identifier": "123",
  "customProps": {
    "fullName": "John doe",
    "pricingPlan": "premium",
    "registeredAt": "2019-08-15T13:20:39.160Z",
    "lastSeenAt": "2019-08-20T17:40:39.160Z"

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! 🤩


  • 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.

Typical error response structure

In general: Codes in the 4xx range indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, or that your request is malformed. Codes in the 5xx range indicate a server error on the Sidemail's side.

developerMessageA brief description of the error. Usually contains instruction on how to resolve the issue.
errorCodeAn error code. Search the appropriate section in this API documentation to find out more about the error.
moreInfoA link to the appropriate documentation.

Available JSON body parameters

identifierstringUnique string, that represent user in your system. It's recommended to use identifier and not just rely on email.
emailAddressstringUser'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.
isSubscribedbooleanSpecifies if Sidemail should set contact's status to subscribed or unsubscribed.
timezonestringOptionally set and update contact's timezone, this has to be a valid timezone. This is useful for timezone based delivery with Messenger.
customPropsobjectSpecify 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.
groupsarrayAn array where each item must be group ID (string). To see a group ID, navigate to groups page in your project, and click on some group. The group ID is displayed below "Edit group" title in the edit modal window. ​Group ID has this format: "5d45dd1ca546d200fe201f83".

Find contact via API

Read contact data from Sidemail by creating GET API request to the following URL:


Replace with email address of contact you're searching for.

Delete contact via API

Delete contact from Sidemail by creating DELETE API request to the following URL:


Replace with email address of contact you're trying to delete.