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): Template variables. Values accept the same forms as the Email API: strings, number arrays, or arrays of objects used by dynamic template components.
  • 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. Its nested filter.match controls how rules inside the filter are combined and defaults to "all" (see Contacts API).
    • match ("all" or "any", optional): Controls how the top-level contactId, groupId, and filter selectors are combined. Defaults to "any" when creating a draft.
    • 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.

Recipient matching

  • recipients.match: Combines contactId, groupId, and filter. Default is "any" when creating a draft.
  • recipients.filter.match: Combines rules inside filter.rules. Default is "all".
  • isSubscribed: Always applied as an additional AND condition.

Messenger draft updates are partial. Recipient fields omitted from an update retain their existing values. Set unused contactId, groupId, or filter fields to null to remove them.

Multiple IDs within groupId match contacts belonging to any of the supplied groups. A draft without contactId, groupId, or filter targets all subscribed contacts.

Check the recipient count before queueing

Use the Contacts query endpoint with the same recipient query before queueing a Messenger draft. The response includes the number of matching contacts in totalCount.

Example request:

{
  "isSubscribed": true,
  "groupId": ["5d45dd1ca546d200fe201f83"],
  "match": "all",
  "filter": {
    "match": "all",
    "rules": [
      {
        "field": "customProps.plan",
        "operator": "includes",
        "value": "premium"
      }
    ]
  },
  "limit": 1
}

Example response:

{
  "data": [
    /* Array of contact objects */
  ],
  "pageCount": 42,
  "totalCount": 42
}

Provide match explicitly when checking the recipient count. The Contacts query endpoint defaults match to "all", while Messenger draft creation defaults it to "any".

Recipient criteria are evaluated again during delivery. Contact properties and group membership changes made after queueing may affect the final recipients.

Example data:

{
  "id": "5d45dd1ca546d200fe201f84",
  "subject": "Welcome to Sidemail!",
  "fromName": "Sidemail Team",
  "fromAddress": "[email protected]",
  "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": "[email protected]",
  "templateId": "5d45dd1ca546d200fe201f83",
  "templateProps": {
    "firstName": "Patrik",
    "metrics": [12, 19, 7],
    "items": [
      {
        "name": "Pro plan",
        "links": [{ "label": "Open dashboard", "url": "https://example.com" }]
      }
    ]
  },
  "recipients": {
    "groupId": ["5d45dd1ca546d200fe201f83"],
    "match": "all",
    "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.

Recipient fields omitted from an update retain their existing saved values. When changing recipients, explicitly provide top-level recipients.match and set unused selectors to null.

Example request:

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

Example to queue a draft for delivery:

{
  "status": "queued"
}

Setting the status to "queued" begins the delivery process without an additional API confirmation prompt. Verify the saved recipient settings and expected recipient count before queueing.

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
}