Messenger API methods (unstable)

Sidemail Messenger API lets you easily send newsletters, campaigns, and product updates to your users — fully automated, personalized, and managed via API. Create and schedule one-time broadcasts, target any segment of contacts.

Available API endpoints:

• GET https://api.sidemail.io/v1/messenger — List all Messenger drafts
• GET https://api.sidemail.io/v1/messenger/{id} — Get a Messenger draft
• POST https://api.sidemail.io/v1/messenger — Create a Messenger draft
• PATCH https://api.sidemail.io/v1/messenger/{id} — Update a Messenger draft
• DELETE https://api.sidemail.io/v1/messenger/{id} — Delete a Messenger draft

Messenger Object

A Messenger draft object represents a single message draft.

• id (string): Unique identifier of the Messenger draft.
• subject (string): Subject line of the Messenger. Defaults to Untitled draft.
• fromName (string, optional): Name of the sender.
• fromAddress (string): Email address of the sender.
• html (string, optional): HTML content of the message (used if not using template).
• richTextValue (object or null, optional): Rich text content, or null if not set.
• templateId (string or null, optional): Template ID to use.
• templateProps (object, optional): Key-value pairs for template variables.
• recipients (object): Recipients query object. See Contacts API.
  • contactId (string or array of strings, optional): List of contact IDs.
  • groupId (string or array of strings, optional): List of group IDs.
  • filter (object, optional): Advanced filter object (see Contacts API).
  • match ("all" or "any", optional): Whether all or any recipient rules must match.
  • isSubscribed (boolean, optional): Only accepts true, defaults to true.
• scheduledAt (string or null, optional): ISO8601 date string for scheduled delivery, or null.
• isTimezoneScheduled (boolean): Whether to schedule by recipient timezone. Defaults to false.
• contentType (string): One of "with-layout", "no-layout", or "template". Defaults to "with-layout".
• status (string): One of "draft", "queued", "scheduled", "processing", "DONE". Only "draft" and "queued" statuses are editable. Defaults to "draft".
• createdAt (string): ISO8601 date string when the Messenger was created.
• stats (object, not editable): Stats object (see below). Only defined after a draft is queued.
  • totalRecipients (number): Total recipients.
  • unsubscribedTotal (number): Unsubscribed recipients.
  • deliveriesTotal (number): Delivered messages.
  • complaintsTotal (number): Complaints received.
  • bouncesTotal (number): Bounced emails.
  • uniqueOpensTotal (number): Unique opens.

Example data:

{
  "id": "5d45dd1ca546d200fe201f84",
  "subject": "Welcome to Sidemail!",
  "fromName": "Sidemail Team",
  "fromAddress": "team@yourdomain.com",
  "html": "<p>Hello {{contact.name}}, welcome!</p>",
  "richTextValue": null,
  "templateId": null,
  "templateProps": null,
  "recipients": {
    "contactId": null,
    "groupId": ["5d45dd1ca546d200fe201f83"],
    "filter": {
      "match": "all",
      "rules": [
        { "field": "customProps.plan", "operator": "includes", "value": "premium" },
        { "field": "createdAt", "operator": "gte", "value": "2025-01-01T00:00:00.000Z" }
      ]
    },
    "match": "all",
    "isSubscribed": true
  },
  "scheduledAt": "2025-05-10T09:00:00.000Z",
  "isTimezoneScheduled": false,
  "contentType": "with-layout",
  "status": "DONE",
  "createdAt": "2025-05-04T12:00:00.000Z",
  "stats": {
    "totalRecipients": 1500,
    "unsubscribedTotal": 5,
    "deliveriesTotal": 1490,
    "complaintsTotal": 1,
    "bouncesTotal": 4,
    "uniqueOpensTotal": 900
  }
}

Get a Messenger draft

GET https://api.sidemail.io/v1/messenger/:id

Returns

Example response:

{ "data": {/* Messenger object */ } }

List Messenger drafts

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

Query string parameters

• offset (number, optional): Number of drafts to skip (pagination). Default: 0.
• limit (number, optional): Number of drafts per page. Default: 20.

Returns

Example response:

{
  "data": [/* ... */],
  "pageCount": 5,
  "totalCount": 42
}

Create a Messenger draft

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

The request body must be a valid Messenger draft object (see above)

Example request:

{
  "subject": "Welcome!",
  "fromAddress": "team@yourdomain.com",
  "templateId": "5d45dd1ca546d200fe201f83",
  "recipients": { "filter": { "match": "all", "rules": [ { "field": "customProps.plan", "operator": "includes", "value": "premium" } ] } },
  "scheduledAt": "2025-05-04T12:00:00.000Z"
}

Returns

Returns the created Messenger draft object (see above).

Update a Messenger draft

PATCH https://api.sidemail.io/v1/messenger/:id

The request body must be a valid Messenger draft object (see above). Partial updates are supported.

Example request:

{
  "subject": "Updated subject",
  "scheduledAt": "2025-05-05T12:00:00.000Z"
}

Example to queue a draft for delivery:

{
  "status": "queued"
}

Returns

Returns status code 200 on success and an empty JSON object:

{}

Delete a Messenger draft

DELETE https://api.sidemail.io/v1/messenger/:id

Permanently deletes a Messenger draft. It cannot be undone.

Returns

Example response:

{
  "deleted": true
}