Contact profiles API methods

Available API endpoints:

• POST https://api.sidemail.io/v1/contacts — Create or update a contact
• POST https://api.sidemail.io/v1/contacts/query — Query contacts
• GET https://api.sidemail.io/v1/contacts — List all contacts
• GET https://api.sidemail.io/v1/contacts/{emailAddress} — Find a contact
• DELETE https://api.sidemail.io/v1/contacts/{emailAddress} — Delete a contact

Contact Object

A contact object represents a single contact profile.

• emailAddress (string): Email address of the contact.
• identifier (string, optional): Your unique identifier for the contact.
• id (string): Sidemail's unique identifier of the contact.
• projectId (string): Identifier of the project associated with the contact.
• createdAt (string): ISO8601 date string when the contact was created.
• timezone (string, optional): Timezone of the contact (e.g., "Europe/Prague").
• timezoneUtcOffset (number, optional): UTC offset in minutes based on the contact's timezone.
• isSubscribed (boolean): Indicates whether the contact is subscribed.
• gravatarUrl (string, optional): URL of the contact's Gravatar image, automatically generated from their email address.
• subscribedIp (string, optional): IP address from which the contact subscribed.
• subscribedAt (string, optional): ISO8601 date string when the contact subscribed.
• unsubscribedAt (string, optional): ISO8601 date string when the contact unsubscribed.
• sourceType (string): Source of the contact ("api", "bulk-import", "stripe", "hostedform").
• updatedAt (string): ISO8601 date string when the contact was last updated.
• groupIds (array, optional): List of group IDs the contact belongs to.
• customProps (array, optional): List of custom properties associated with the contact.
  • keyName (string): Name of the custom property.
  • value (string | number): Value of the custom property.
  • updatedAt (string): ISO8601 date string when the property was last updated.
• note (string, optional): Additional notes about the contact.

Example data:

{
  "id": "307f1f70bcf86cd799439011",
  "projectId": "507f1f77bcf86cd799439011",
  "emailAddress": "marry@lightling.com",
  "identifier": "123",
  "createdAt": "2019-08-15T13:20:39.160Z",
  "timezone": "Europe/Prague",
  "isSubscribed": true,
  "subscribedAt": "2019-08-15T13:20:39.160Z",
  "subscribedIp": "192.168.1.1",
  "unsubscribedAt": null,
  "sourceType": "api",
  "updatedAt": "2019-08-15T13:20:39.160Z",
  "groupIds": ["257f1f77bcf86cd799439011"],
  "customProps": [
    {
      "keyName": "name",
      "value": "Marry Lightning",
      "updatedAt": "2019-08-15T13:20:39.160Z"
    },
    {
      "keyName": "subscriptionPlan",
      "value": "premium",
      "updatedAt": "2019-08-15T13:20:39.160Z"
    }
  ],
  "note": "VIP customer"
}

Create or update a contact

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

Node.js example:

const configureSidemail = require("sidemail");
const sidemail = configureSidemail({ apiKey: "xxxxx" });
  
const response = await sidemail.contacts.createOrUpdate({
	emailAddress: "john.doe@example.com",
	identifier: "123",
	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 ...
	},
});

Parameters

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 optional
Specifies if Sidemail should set contact's status to subscribed or unsubscribed.

timezone string optional
Optionally set and update contact's timezone, this has to be a valid timezone. This is useful for timezone based delivery with Messenger.

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.

groups array optional
An array where each item must be group ID (string). To see a group ID, navigate to the contact page in your project, hover over a group and click the three-dot icon. The group ID is displayed below "Edit group" title in the edit modal window. ​Group ID has this format: "5d45dd1ca546d200fe201f83".

Returns

If contact was newly created:

{
    "status": "created"
}

or if contact was updated:

{
    "status": "updated"
}

Find a contact

GET https://api.sidemail.io/v1/contacts/:emailAddress

Node.js example:

const configureSidemail = require("sidemail");
const sidemail = configureSidemail({ apiKey: "xxxxx" });
  
const response = await sidemail.contacts.find({
	emailAddress: "marry@lightning.com",
});

Retrieves the contact data. You need only supply the contact email address to the URL.

Parameters

No parameters.

Returns

Returns a contact object if contact was found or null.

{
    contact: {
        "id": "307f1f70bcf86cd799439011",
        "projectId": "507f1f77bcf86cd799439011",
        "emailAddress": "marry@lightling.com",
        "identifier": "123",
        "createdAt": "2019-08-15T13:20:39.160Z",
        "timezone": "Europe/Prague",
        "isSubscribed": true,
        "subscribedAt": "2019-08-15T13:20:39.160Z",
        "unsubscribedAt": null,
        "sourceType": "api",
        "updatedAt": "2019-08-15T13:20:39.160Z",
        "groupIds": ["257f1f77bcf86cd799439011"],
        "customProps": [
            {
                "keyName": "name",
                "value": "Marry Lightning",
                "updatedAt": "2019-08-15T13:20:39.160Z"
            }, {
                "keyName": "subscriptionPlan",
                "value": "premium",
                "updatedAt": "2019-08-15T13:20:39.160Z"
            }
        ],
        "note": null
    }
}

Query contacts (unstable)

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

Retrieve a list of your contacts, with support for advanced filtering, searching, and pagination. The contacts are returned sorted by creation date, with the most recent contacts appearing first.

JSON payload example:

{
  "search": "@blueberry.com",
  "isSubscribed": true,
  "groupId": ["5d45dd1ca546d200fe201f83"],
  "contactId": ["5d45dd1ca546d200fe201f84"],
  "match": "all",
  "filter": {
    "match": "all",
    "rules": [
      { "field": "customProps.plan", "operator": "includes", "value": "premium" },
      { "field": "createdAt", "operator": "gte", "value": "2023-01-01T00:00:00.000Z" }
    ]
  },
  "offset": 0,
  "limit": 20
}

Parameters

contactId string or string[]
Filter by contact ID(s). Supports a single ID or array of IDs.

groupId string or string[]
Filter by group ID(s). Supports a single ID or array of IDs.

search string
Partial email address search, case-insensitive.

isSubscribed boolean optional
Filter by subscription status.

match "all" or "any" optional
Combine top-level filters with AND (all) or OR (any). Default is "all".

filter object optional
Advanced filter object (see below).

offset number optional
Number of contacts to skip (pagination). Default: 0.

limit number optional
Number of contacts per page. Default: 20.

Advanced filter object (filter)

The filter object allows for complex, rule-based filtering:

• match: "all" or "any" (default: "all") — whether all rules must match or any rule can match.
• rules: Array of rule objects. Each rule:
  • field: string (required) — the field to filter on (any contact property, e.g., customProps.keyName, emailAddress, createdAt)
  • operator: string (default is equals) — one of: equals, notEquals, includes, notIncludes, gt, gte, lt, lte, in, notIn, anyValue, noValue
  • value: string or number — the value to compare (can be empty string or null for some operators)

Example filter rule:

{
  "filter": {
    "match": "all",
    "rules": [
      { "field": "timezone", "operator": "includes", "value": "Europe" },
      { "field": "customProps.registeredAt", "operator": "gt", "value": "2024-01-01T00:00:00.000Z" },
      { "field": "customProps.plan", "value": "pro" }
    ]
  }
}

Returns

Returns an object with the following structure:

{
  "data": [ /* Array of contact objects */ ],
  "pageCount": 5,           // Total number of pages
  "totalCount": 42          // Total number of contacts matching the query
}

List all contacts

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

Node.js example:

const configureSidemail = require("sidemail");
const sidemail = configureSidemail({ apiKey: "xxxxx" });
  
const response = await sidemail.contacts.list();
// to paginate: await sidemail.contacts.list({ paginationCursorNext: "123" });

Returns a list of your contacts. The contacts are returned sorted by creation date, with the most recent contacts appearing first.

Parameters

paginationCursorNext string
A cursor for use in pagination. paginationCursorNext is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include paginationCursorNext=obj_foo in order to fetch the next page of the list.

Returns

A object with a data property that contains an array of up to 100 contacts. Each entry in the array is a separate contact object. If no more contacts are available, the resulting array will be empty.

{
    hasMore: true,
    paginationCursorNext: "307f1f70bcf86cd799439011",
    data: [
        {
            "id": "307f1f70bcf86cd799439011",
            "projectId": "507f1f77bcf86cd799439011",
            "emailAddress": "marry@lightling.com",
            "identifier": "123",
            "createdAt": "2019-08-15T13:20:39.160Z",
            "timezone": "Europe/Prague",
            "isSubscribed": true,
            "subscribedAt": "2019-08-15T13:20:39.160Z",
            "unsubscribedAt": null,
            "sourceType": "api",
            "updatedAt": "2019-08-15T13:20:39.160Z",
            "groupIds": ["257f1f77bcf86cd799439011"],
            "customProps": [
                {
                    "keyName": "name",
                    "value": "Marry Lightning",
                    "updatedAt": "2019-08-15T13:20:39.160Z"
                }, {
                    "keyName": "subscriptionPlan",
                    "value": "premium",
                    "updatedAt": "2019-08-15T13:20:39.160Z"
                }
            ],
            "note": null
        }
        // Another 99 contacts...
    ]
}

Delete a contact

DELETE https://api.sidemail.io/v1/contacts/:emailAddress

const configureSidemail = require("sidemail");
const sidemail = configureSidemail({ apiKey: "xxxxx" });
  
const response = await sidemail.contacts.delete({
	emailAddress: "marry@lightning.com",
});

Permanently deletes a contact. It cannot be undone.

Parameters

No parameters.

Returns

Returns an object with deleted parameter that indicates the outcome of the operation.

{
    "deleted": true
}