Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Notification

A notification is one outbound or inbound delivery — an email that leaves the system because something happened on a ticket, or a message that arrived. They are created by the system, never by a client; these endpoints exist to see what happened and to push a failed delivery back into the queue.

Status
Meaning

PENDING

waiting for its next attempt

DELIVERING

being handed to the transport right now

DELIVERED

done

DEAD

given up on after repeated failures; lastError says why

List notifications

get

Returns the caller's own notification feed — one entry per notification that was addressed to them, newest last unless sort says otherwise. Entries of other users are never returned, whatever the filter says.

Filterable — id, userId, notificationId, readAt.

Sortable — id, createdAt.

Searchable — nothing yet.

readAt is when the caller marked the entry as read and is empty while it is unread — unread entries are {"field":"readAt","op":"isNull"}. The notification behind an entry, with its status and delivery history, is fetched with fields=notification.

Authorizations
AuthorizationstringRequired

Token issued by the central equipme authentication, sent as Bearer <token>.

Query parameters
filterstringOptional

JSON filter expression

searchstringOptional

Free-text term — no effect here

sortstringOptional

Comma-separated field:direction terms

fieldsstringOptional

Selection of fields and relations

Example: status,attempts,lastError
offsetintegerOptional

Number of entries to skip

Default: 0
limitintegerOptional

Page size, 1 to 100

Default: 100
Responses
200

OK

application/json
countintegerOptional
get/v1/notifications
GET /api/v1/notifications HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 1,
  "data": [
    {
      "createdAt": "text",
      "id": 1,
      "notification": {
        "attempts": 1,
        "channel": {
          "active": true,
          "createdAt": "text",
          "id": 1,
          "kind": "",
          "name": "text",
          "purpose": "",
          "tenant": {
            "id": 1,
            "name": "text"
          },
          "tenantId": 1,
          "updatedAt": "text"
        },
        "channelId": 1,
        "config": [
          1
        ],
        "createdAt": "text",
        "deliveredAt": "text",
        "direction": "INBOUND",
        "event": {
          "actorId": 1,
          "actorSnapshot": [
            1
          ],
          "aggregateChanges": [
            1
          ],
          "aggregateId": 1,
          "aggregateSnapshot": null,
          "aggregateType": "text",
          "attempts": 1,
          "eventType": "CREATED",
          "id": 1,
          "lastError": "text",
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "nextAttemptAt": "text",
          "occurredAt": "text",
          "publishedAt": "text",
          "scopeId": 1,
          "scopeType": "text",
          "status": "PENDING",
          "tenantId": 1
        },
        "eventId": 1,
        "externalMessageId": "text",
        "id": 1,
        "identity": {
          "createdAt": "text",
          "groups": [
            "[Circular Reference]"
          ],
          "id": 1,
          "type": "",
          "value": "text",
          "verifiedAt": "text"
        },
        "identityId": 1,
        "lastError": "text",
        "nextAttemptAt": "text",
        "payload": [
          1
        ],
        "status": "PENDING",
        "tenantId": 1
      },
      "notificationId": 1,
      "readAt": "text",
      "userId": 1
    }
  ]
}

Get a notification

get

Returns a single notification — the delivery itself, not a feed entry: which channel and address it went to, how often it was attempted, when it was delivered and what the last error was.

Authorizations
AuthorizationstringRequired

Token issued by the central equipme authentication, sent as Bearer <token>.

Path parameters
idintegerRequired

Notification id

Example: 9100
Query parameters
fieldsstringOptional

Selection of fields and relations

Example: status,attempts,lastError
Responses
200

OK

application/json
get/v1/notifications/{id}
GET /api/v1/notifications/{id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "attempts": 1,
    "channel": {
      "active": true,
      "createdAt": "text",
      "id": 1,
      "kind": "",
      "name": "text",
      "purpose": "",
      "tenant": {
        "id": 1,
        "name": "text"
      },
      "tenantId": 1,
      "updatedAt": "text"
    },
    "channelId": 1,
    "config": [
      1
    ],
    "createdAt": "text",
    "deliveredAt": "text",
    "direction": "INBOUND",
    "event": {
      "actorId": 1,
      "actorSnapshot": [
        1
      ],
      "aggregateChanges": [
        1
      ],
      "aggregateId": 1,
      "aggregateSnapshot": null,
      "aggregateType": "text",
      "attempts": 1,
      "eventType": "CREATED",
      "id": 1,
      "lastError": "text",
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "nextAttemptAt": "text",
      "occurredAt": "text",
      "publishedAt": "text",
      "scopeId": 1,
      "scopeType": "text",
      "status": "PENDING",
      "tenantId": 1
    },
    "eventId": 1,
    "externalMessageId": "text",
    "id": 1,
    "identity": {
      "createdAt": "text",
      "groups": [
        {
          "assignmentContext": "text",
          "autoAssign": true,
          "contactId": 1,
          "description": "text",
          "email": "text",
          "id": 1,
          "members": [
            "[Circular Reference]"
          ],
          "name": "text",
          "phone": "text",
          "tenant": {
            "id": 1,
            "name": "text"
          },
          "tenantId": 1
        }
      ],
      "id": 1,
      "type": "",
      "value": "text",
      "verifiedAt": "text"
    },
    "identityId": 1,
    "lastError": "text",
    "nextAttemptAt": "text",
    "payload": [
      1
    ],
    "status": "PENDING",
    "tenantId": 1
  }
}

Retry a failed delivery

post

Puts a failed delivery back into the queue: the notification is set to PENDING, its last error is cleared and the next attempt is scheduled immediately. Answers with 202.

Only an outbound notification that has been given up on (DEAD) is taken back. Anything else is left untouched — the request still answers with 202, so check the notification afterwards if it matters.

Authorizations
AuthorizationstringRequired

Token issued by the central equipme authentication, sent as Bearer <token>.

Path parameters
idintegerRequired

Notification id

Example: 9100
Responses
202

Accepted

No content
post/v1/notifications/{id}/retry
POST /api/v1/notifications/{id}/retry HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Last updated

Was this helpful?