Mankomail

Notifications and incidents ​

Routes are relative to <PUBLIC_BASE_URL>; request and response bodies are JSON unless stated otherwise. Authentication, scopes, pagination and the error format are described in the REST API guides.

GET /api/v1/executions/summary ​

Summarise recent executions

Counters since since (24 hours by default, 30 days at most), per workflow: what breaks, and where. A since out of bounds is clamped, and the applied value is returned.

Access — Member session or API key with scope notifications:read.

Parameters

NameInTypeRequired
sincequerystring (date-time)no

Responses

200 — The counters.

FieldTypeRequired
sincestringyes
totalintegeryes
failedintegeryes
runningintegeryes
succeededintegeryes
lastFailedAtstring | nullyes
byWorkflowobject[]yes
JSON Schema
json
{
  "type": "object",
  "properties": {
    "since": { "type": "string" },
    "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
    "failed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
    "running": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
    "succeeded": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
    "lastFailedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
    "byWorkflow": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "workflowId": { "type": "string" },
          "name": { "type": "string" },
          "failed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
          "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
          "lastFailedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
        },
        "required": [ "workflowId", "name", "failed", "total", "lastFailedAt" ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "since",
    "total",
    "failed",
    "running",
    "succeeded",
    "lastFailedAt",
    "byWorkflow"
  ],
  "additionalProperties": false
}

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — request.bad_request. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

GET /api/v1/executions/incidents ​

List execution incidents

One incident per failed execution, with the faulty node and an anonymised error summary, paginated by cursor. unacknowledged=true keeps what was not acknowledged yet.

Access — Member session or API key with scope notifications:read.

Parameters

NameInTypeRequired
sincequerystring (date-time)no
cursorquerystringno
limitqueryintegerno
unacknowledgedquerystringno

Responses

200 — A page of incidents.

FieldTypeRequired
itemsobject[]yes
nextCursorstring | nullyes
JSON Schema
json
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "executionId": { "type": "string" },
          "workflowId": { "type": "string" },
          "workflowName": { "type": "string" },
          "mailboxId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "failedAt": { "type": "string" },
          "errorSummary": { "type": "string", "maxLength": 200 },
          "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "nodeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
          "acknowledgedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
        },
        "required": [
          "id",
          "executionId",
          "workflowId",
          "workflowName",
          "mailboxId",
          "failedAt",
          "errorSummary",
          "nodeId",
          "nodeName",
          "acknowledgedAt"
        ],
        "additionalProperties": false
      }
    },
    "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }
  },
  "required": [ "items", "nextCursor" ],
  "additionalProperties": false
}

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — request.bad_request. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

POST /api/v1/executions/incidents/{id}/acknowledge ​

Acknowledge an incident

Marks the incident as seen. Idempotent: acknowledging twice keeps the first instant. An incident of another member is a 404.

Access — Member session or API key with scope notifications:write.

Parameters

NameInTypeRequired
idpathstringyes

Responses

200 — The incident, acknowledged.

FieldTypeRequired
acknowledgedAtstringyes
JSON Schema
json
{
  "type": "object",
  "properties": { "acknowledgedAt": { "type": "string" } },
  "required": [ "acknowledgedAt" ],
  "additionalProperties": false
}

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — incident.not_found. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

GET /api/v1/notifications ​

List my notifications

The feed, cursor-paginated, with the global unread count in the same answer. Archived notifications never appear. unread=true keeps only the unread ones.

Access — Member session or API key with scope notifications:read.

Parameters

NameInTypeRequired
unreadquerystringno
cursorquerystringno
limitqueryintegerno

Responses

200 — A page of the feed.

FieldTypeRequired
itemsobject[]yes
nextCursorstring | nullyes
unreadCountintegeryes
JSON Schema
json
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "severity": { "type": "string", "enum": [ "info", "warning", "error" ] },
              "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "createdAt": { "type": "string" },
              "readAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "kind": { "type": "string", "const": "execution.failed" },
              "params": {
                "type": "object",
                "properties": {
                  "workflowId": { "type": "string" },
                  "workflowName": { "type": "string" },
                  "executionId": { "type": "string" },
                  "errorSummary": { "type": "string", "maxLength": 200 }
                },
                "required": [ "workflowId", "workflowName", "executionId", "errorSummary" ],
                "additionalProperties": false
              }
            },
            "required": [
              "id",
              "severity",
              "link",
              "createdAt",
              "readAt",
              "kind",
              "params"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "severity": { "type": "string", "enum": [ "info", "warning", "error" ] },
              "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "createdAt": { "type": "string" },
              "readAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "kind": { "type": "string", "const": "mailbox.error" },
              "params": {
                "type": "object",
                "properties": {
                  "mailboxId": { "type": "string" },
                  "address": { "type": "string" },
                  "kind": { "type": "string" }
                },
                "required": [ "mailboxId", "address", "kind" ],
                "additionalProperties": false
              }
            },
            "required": [
              "id",
              "severity",
              "link",
              "createdAt",
              "readAt",
              "kind",
              "params"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "severity": { "type": "string", "enum": [ "info", "warning", "error" ] },
              "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "createdAt": { "type": "string" },
              "readAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "kind": { "type": "string", "const": "mailbox.recovered" },
              "params": {
                "type": "object",
                "properties": {
                  "mailboxId": { "type": "string" },
                  "address": { "type": "string" }
                },
                "required": [ "mailboxId", "address" ],
                "additionalProperties": false
              }
            },
            "required": [
              "id",
              "severity",
              "link",
              "createdAt",
              "readAt",
              "kind",
              "params"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "severity": { "type": "string", "enum": [ "info", "warning", "error" ] },
              "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "createdAt": { "type": "string" },
              "readAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "kind": { "type": "string", "const": "mailbox.removed" },
              "params": {
                "type": "object",
                "properties": {
                  "mailboxId": { "type": "string" },
                  "address": { "type": "string" },
                  "mode": { "type": "string", "enum": [ "disconnected", "deleted" ] },
                  "unpublishedWorkflows": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  }
                },
                "required": [ "mailboxId", "address", "mode", "unpublishedWorkflows" ],
                "additionalProperties": false
              }
            },
            "required": [
              "id",
              "severity",
              "link",
              "createdAt",
              "readAt",
              "kind",
              "params"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "severity": { "type": "string", "enum": [ "info", "warning", "error" ] },
              "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "createdAt": { "type": "string" },
              "readAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "kind": { "type": "string", "const": "approval.pending" },
              "params": {
                "type": "object",
                "properties": {
                  "approvalId": { "type": "string" },
                  "workflowName": { "type": "string" },
                  "subject": {
                    "anyOf": [
                      { "type": "string", "maxLength": 120 },
                      { "type": "null" }
                    ]
                  }
                },
                "required": [ "approvalId", "workflowName", "subject" ],
                "additionalProperties": false
              }
            },
            "required": [
              "id",
              "severity",
              "link",
              "createdAt",
              "readAt",
              "kind",
              "params"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "severity": { "type": "string", "enum": [ "info", "warning", "error" ] },
              "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "createdAt": { "type": "string" },
              "readAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "kind": { "type": "string", "const": "analyzer.ready" },
              "params": {
                "type": "object",
                "properties": {
                  "mailboxId": { "type": "string" },
                  "reportId": { "type": "string" },
                  "opportunities": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  }
                },
                "required": [ "mailboxId", "reportId", "opportunities" ],
                "additionalProperties": false
              }
            },
            "required": [
              "id",
              "severity",
              "link",
              "createdAt",
              "readAt",
              "kind",
              "params"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "severity": { "type": "string", "enum": [ "info", "warning", "error" ] },
              "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "createdAt": { "type": "string" },
              "readAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "kind": { "type": "string", "const": "analyzer.failed" },
              "params": {
                "type": "object",
                "properties": {
                  "mailboxId": { "type": "string" },
                  "reason": { "type": "string", "maxLength": 120 }
                },
                "required": [ "mailboxId", "reason" ],
                "additionalProperties": false
              }
            },
            "required": [
              "id",
              "severity",
              "link",
              "createdAt",
              "readAt",
              "kind",
              "params"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "severity": { "type": "string", "enum": [ "info", "warning", "error" ] },
              "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "createdAt": { "type": "string" },
              "readAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "kind": { "type": "string", "const": "member.joined" },
              "params": {
                "type": "object",
                "properties": {
                  "memberId": { "type": "string" },
                  "name": { "type": "string" }
                },
                "required": [ "memberId", "name" ],
                "additionalProperties": false
              }
            },
            "required": [
              "id",
              "severity",
              "link",
              "createdAt",
              "readAt",
              "kind",
              "params"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "severity": { "type": "string", "enum": [ "info", "warning", "error" ] },
              "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "createdAt": { "type": "string" },
              "readAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "kind": { "type": "string", "const": "workflow.paused" },
              "params": {
                "type": "object",
                "properties": {
                  "workflowId": { "type": "string" },
                  "workflowName": { "type": "string" }
                },
                "required": [ "workflowId", "workflowName" ],
                "additionalProperties": false
              }
            },
            "required": [
              "id",
              "severity",
              "link",
              "createdAt",
              "readAt",
              "kind",
              "params"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "severity": { "type": "string", "enum": [ "info", "warning", "error" ] },
              "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "createdAt": { "type": "string" },
              "readAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "kind": { "type": "string", "const": "workflow.trigger_error" },
              "params": {
                "type": "object",
                "properties": {
                  "workflowId": { "type": "string" },
                  "workflowName": { "type": "string" },
                  "nodeId": { "type": "string" },
                  "integration": { "type": "string", "maxLength": 64 },
                  "code": { "type": "string", "maxLength": 120 }
                },
                "required": [
                  "workflowId",
                  "workflowName",
                  "nodeId",
                  "integration",
                  "code"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "id",
              "severity",
              "link",
              "createdAt",
              "readAt",
              "kind",
              "params"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "severity": { "type": "string", "enum": [ "info", "warning", "error" ] },
              "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "createdAt": { "type": "string" },
              "readAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "kind": { "type": "string", "const": "contacts.enrichment_ready" },
              "params": {
                "type": "object",
                "properties": {
                  "mailboxId": { "type": "string" },
                  "address": { "type": "string" },
                  "contacts": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "withProposal": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  }
                },
                "required": [ "mailboxId", "address", "contacts", "withProposal" ],
                "additionalProperties": false
              }
            },
            "required": [
              "id",
              "severity",
              "link",
              "createdAt",
              "readAt",
              "kind",
              "params"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "severity": { "type": "string", "enum": [ "info", "warning", "error" ] },
              "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "createdAt": { "type": "string" },
              "readAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
              "kind": { "type": "string", "const": "system.info" },
              "params": {
                "type": "object",
                "properties": {
                  "messageKey": { "type": "string", "maxLength": 120 },
                  "params": {
                    "default": {},
                    "type": "object",
                    "propertyNames": { "type": "string" },
                    "additionalProperties": {
                      "anyOf": [
                        { "type": "string" },
                        { "type": "number" },
                        { "type": "boolean" }
                      ]
                    }
                  }
                },
                "required": [ "messageKey", "params" ],
                "additionalProperties": false
              }
            },
            "required": [
              "id",
              "severity",
              "link",
              "createdAt",
              "readAt",
              "kind",
              "params"
            ],
            "additionalProperties": false
          }
        ]
      }
    },
    "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
    "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
  },
  "required": [ "items", "nextCursor", "unreadCount" ],
  "additionalProperties": false
}

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — request.bad_request. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

GET /api/v1/notifications/unread-count ​

Count my unread notifications

The badge alone: the one call a client repeats after a reconnection.

Access — Member session or API key with scope notifications:read.

Responses

200 — The count.

FieldTypeRequired
unreadCountintegeryes
JSON Schema
json
{
  "type": "object",
  "properties": {
    "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
  },
  "required": [ "unreadCount" ],
  "additionalProperties": false
}

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

POST /api/v1/notifications/read-all ​

Mark every notification as read

Access — Member session or API key with scope notifications:write.

Responses

200 — How many rows changed.

FieldTypeRequired
countintegeryes
JSON Schema
json
{
  "type": "object",
  "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } },
  "required": [ "count" ],
  "additionalProperties": false
}

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

POST /api/v1/notifications/{id}/read ​

Mark a notification as read

Idempotent: marking twice returns the first timestamp. Another member’s notification is a 404.

Access — Member session or API key with scope notifications:write.

Parameters

NameInTypeRequired
idpathstringyes

Responses

200 — When it was read.

FieldTypeRequired
readAtstringyes
JSON Schema
json
{
  "type": "object",
  "properties": { "readAt": { "type": "string" } },
  "required": [ "readAt" ],
  "additionalProperties": false
}

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — notification.not_found. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

POST /api/v1/notifications/{id}/archive ​

Archive a notification

Removes it from the feed and marks it read. Frees the deduplication key: the same incident a month later produces a new line.

Access — Member session or API key with scope notifications:write.

Parameters

NameInTypeRequired
idpathstringyes

Responses

204 — Archived.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — notification.not_found. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.