Contact profiles API methods

Available API endpoints:

• POST https://api.sidemail.io/v1/contacts
• GET https://api.sidemail.io/v1/contacts
• GET https://api.sidemail.io/v1/contacts/:emailAddress
• DELETE https://api.sidemail.io/v1/contacts/:emailAddress

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
    }
}

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
}