Mankomail

Notifications et incidents ​

Les routes sont relatives à <PUBLIC_BASE_URL> ; les corps de requête et de réponse sont en JSON sauf mention contraire. L’authentification, les portées, la pagination et le format des erreurs sont décrits dans les guides de l’API REST.

GET /api/v1/executions/summary ​

Résumer les exécutions récentes

Les compteurs depuis since (24 h par défaut, 30 jours au plus), par workflow : ce qui casse, et où. Un since hors bornes est ramené dans la fenêtre, et la valeur appliquée est rendue.

Accès — Session de membre ou clé d’API portant notifications:read.

Paramètres

NomOùTypeRequis
sincerequêtestring (date-time)non

Réponses

200 — Les compteurs.

ChampTypeRequis
sincestringoui
totalintegeroui
failedintegeroui
runningintegeroui
succeededintegeroui
lastFailedAtstring | nulloui
byWorkflowobject[]oui
Schéma JSON
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 — La requête ne respecte pas son schéma.

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — request.bad_request. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

GET /api/v1/executions/incidents ​

Lister les incidents d’exécution

Un incident par exécution échouée, avec le nœud fautif et un résumé d’erreur anonymisé, paginé par curseur. unacknowledged=true ne garde que ce qui n’a pas été acquitté.

Accès — Session de membre ou clé d’API portant notifications:read.

Paramètres

NomOùTypeRequis
sincerequêtestring (date-time)non
cursorrequêtestringnon
limitrequêteintegernon
unacknowledgedrequêtestringnon

Réponses

200 — Une page d’incidents.

ChampTypeRequis
itemsobject[]oui
nextCursorstring | nulloui
Schéma JSON
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 — La requête ne respecte pas son schéma.

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — request.bad_request. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

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

Acquitter un incident

Marque l’incident comme vu. Idempotent : acquitter deux fois garde le premier instant. L’incident d’un autre membre est un 404.

Accès — Session de membre ou clé d’API portant notifications:write.

Paramètres

NomOùTypeRequis
idcheminstringoui

Réponses

200 — L’incident, acquitté.

ChampTypeRequis
acknowledgedAtstringoui
Schéma JSON
json
{
  "type": "object",
  "properties": { "acknowledgedAt": { "type": "string" } },
  "required": [ "acknowledgedAt" ],
  "additionalProperties": false
}

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — incident.not_found. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

GET /api/v1/notifications ​

Lister mes notifications

Le fil, paginé par curseur, avec le compteur global de non-lues dans la même réponse. Les archivées n’apparaissent jamais. unread=true ne garde que les non-lues.

Accès — Session de membre ou clé d’API portant notifications:read.

Paramètres

NomOùTypeRequis
unreadrequêtestringnon
cursorrequêtestringnon
limitrequêteintegernon

Réponses

200 — Une page du fil.

ChampTypeRequis
itemsobject[]oui
nextCursorstring | nulloui
unreadCountintegeroui
Schéma JSON
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 — La requête ne respecte pas son schéma.

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — request.bad_request. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

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

Compter mes notifications non lues

La pastille seule : le seul appel qu’un client répète après une reconnexion.

Accès — Session de membre ou clé d’API portant notifications:read.

Réponses

200 — Le compte.

ChampTypeRequis
unreadCountintegeroui
Schéma JSON
json
{
  "type": "object",
  "properties": {
    "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
  },
  "required": [ "unreadCount" ],
  "additionalProperties": false
}

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

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

Marquer toutes les notifications comme lues

Accès — Session de membre ou clé d’API portant notifications:write.

Réponses

200 — Combien de lignes ont changé.

ChampTypeRequis
countintegeroui
Schéma JSON
json
{
  "type": "object",
  "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } },
  "required": [ "count" ],
  "additionalProperties": false
}

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

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

Marquer une notification comme lue

Idempotent : marquer deux fois rend le premier horodatage. La notification d’un autre membre est un 404.

Accès — Session de membre ou clé d’API portant notifications:write.

Paramètres

NomOùTypeRequis
idcheminstringoui

Réponses

200 — Quand elle a été lue.

ChampTypeRequis
readAtstringoui
Schéma JSON
json
{
  "type": "object",
  "properties": { "readAt": { "type": "string" } },
  "required": [ "readAt" ],
  "additionalProperties": false
}

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — notification.not_found. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

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

Archiver une notification

La retire du fil et la marque lue. Libère la clé de déduplication : la même panne un mois plus tard produit une nouvelle ligne.

Accès — Session de membre ou clé d’API portant notifications:write.

Paramètres

NomOùTypeRequis
idcheminstringoui

Réponses

204 — Archivée.

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — notification.not_found. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.