Mankomail

Connexions ​

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/credentials ​

Lister mes connexions

Les connexions du membre, puis celles de l’organisation. Sans type, tous les types gérables ; avec, un seul type, comptes OAuth compris (lecture seule). Jamais un secret.

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

Paramètres

NomOùTypeRequis
typerequête"http_generic" | "imap" | "llm_provider" | "gmail_oauth" | "msgraph_oauth" | stringnon

Réponses

200 — Les connexions.

ChampTypeRequis
itemsobject[]oui
Schéma JSON
json
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "type": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "http_generic",
                  "imap",
                  "llm_provider",
                  "gmail_oauth",
                  "msgraph_oauth"
                ]
              },
              { "type": "string" }
            ]
          },
          "name": { "type": "string" },
          "scope": { "type": "string", "enum": [ "member", "org" ] },
          "kind": { "type": "string", "enum": [ "apiKey", "bearer", "basic", "query" ] },
          "integration": { "type": "string" },
          "hint": { "type": "string", "maxLength": 4 },
          "environment": { "type": "string" },
          "capabilities": { "type": "array", "items": { "type": "string" } },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
          }
        },
        "required": [ "id", "type", "name", "scope", "createdAt", "updatedAt" ],
        "additionalProperties": false
      }
    }
  },
  "required": [ "items" ],
  "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 — credential.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/credentials ​

Créer une connexion

Stocke le secret chiffré et ne rend que son identifiant. scope: "org" est réservé aux administrateurs. Refusée quand l’instance n’a pas de clé de chiffrement.

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

Corps de la requête (application/json)

Type : object

Schéma JSON
json
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "type": { "type": "string", "const": "http_generic" },
        "name": { "type": "string", "minLength": 1, "maxLength": 80 },
        "scope": { "type": "string", "enum": [ "member", "org" ] },
        "data": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "kind": { "type": "string", "const": "apiKey" },
                "headerName": { "type": "string", "minLength": 1, "maxLength": 128 },
                "value": { "type": "string", "minLength": 1, "maxLength": 4096 }
              },
              "required": [ "kind", "headerName", "value" ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "kind": { "type": "string", "const": "bearer" },
                "token": { "type": "string", "minLength": 1, "maxLength": 4096 }
              },
              "required": [ "kind", "token" ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "kind": { "type": "string", "const": "basic" },
                "username": { "type": "string", "minLength": 1, "maxLength": 256 },
                "password": { "type": "string", "minLength": 1, "maxLength": 4096 }
              },
              "required": [ "kind", "username", "password" ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "kind": { "type": "string", "const": "query" },
                "paramName": { "type": "string", "minLength": 1, "maxLength": 128 },
                "value": { "type": "string", "minLength": 1, "maxLength": 4096 }
              },
              "required": [ "kind", "paramName", "value" ],
              "additionalProperties": false
            }
          ]
        }
      },
      "required": [ "type", "name", "scope", "data" ]
    },
    {
      "type": "object",
      "properties": {
        "type": { "type": "string" },
        "name": { "type": "string", "minLength": 1, "maxLength": 80 },
        "scope": { "type": "string", "enum": [ "member", "org" ] },
        "data": {
          "type": "object",
          "propertyNames": { "type": "string" },
          "additionalProperties": { "type": "string" }
        }
      },
      "required": [ "type", "name", "scope", "data" ]
    }
  ]
}

Réponses

201 — L’identifiant de la connexion.

ChampTypeRequis
idstring (uuid)oui
Schéma JSON
json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": [ "id" ],
  "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.

Cette opération accepte un en-tête Idempotency-Key : rejouer la même requête avec la même clé rend la réponse d’origine au lieu d’agir deux fois. Voir Idempotence.

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

Exemple de requête

json
{
  "type": "http_generic",
  "name": "CRM API",
  "scope": "member",
  "data": { "kind": "bearer", "token": "crm_live_example_token" }
}

Exemple de réponse (201)

json
{ "id": "0192f1c2-3b4d-7e8f-9a0b-1c2d3e4f5a6b" }

PUT /api/v1/credentials/{id} ​

Renommer ou remplacer une connexion

Sans data, le secret est conservé (un simple renommage). Avec, le secret est remplacé entièrement, jamais fusionné. Une connexion hors du périmètre du membre est un 404, jamais un 403.

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

Paramètres

NomOùTypeRequis
idcheminstringoui

Corps de la requête (application/json)

ChampTypeRequis
namestringnon
dataobjectnon
Schéma JSON
json
{
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1, "maxLength": 80 },
    "data": {
      "anyOf": [
        {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "kind": { "type": "string", "const": "apiKey" },
                "headerName": { "type": "string", "minLength": 1, "maxLength": 128 },
                "value": { "type": "string", "minLength": 1, "maxLength": 4096 }
              },
              "required": [ "kind", "headerName", "value" ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "kind": { "type": "string", "const": "bearer" },
                "token": { "type": "string", "minLength": 1, "maxLength": 4096 }
              },
              "required": [ "kind", "token" ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "kind": { "type": "string", "const": "basic" },
                "username": { "type": "string", "minLength": 1, "maxLength": 256 },
                "password": { "type": "string", "minLength": 1, "maxLength": 4096 }
              },
              "required": [ "kind", "username", "password" ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "kind": { "type": "string", "const": "query" },
                "paramName": { "type": "string", "minLength": 1, "maxLength": 128 },
                "value": { "type": "string", "minLength": 1, "maxLength": 4096 }
              },
              "required": [ "kind", "paramName", "value" ],
              "additionalProperties": false
            }
          ]
        },
        {
          "type": "object",
          "propertyNames": { "type": "string" },
          "additionalProperties": { "type": "string" }
        }
      ]
    }
  }
}

Réponses

200 — La connexion, modifiée.

ChampTypeRequis
credentialobjectoui
Schéma JSON
json
{
  "type": "object",
  "properties": {
    "credential": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "type": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "http_generic",
                "imap",
                "llm_provider",
                "gmail_oauth",
                "msgraph_oauth"
              ]
            },
            { "type": "string" }
          ]
        },
        "name": { "type": "string" },
        "scope": { "type": "string", "enum": [ "member", "org" ] },
        "kind": { "type": "string", "enum": [ "apiKey", "bearer", "basic", "query" ] },
        "integration": { "type": "string" },
        "hint": { "type": "string", "maxLength": 4 },
        "environment": { "type": "string" },
        "capabilities": { "type": "array", "items": { "type": "string" } },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        }
      },
      "required": [ "id", "type", "name", "scope", "createdAt", "updatedAt" ],
      "additionalProperties": false
    }
  },
  "required": [ "credential" ],
  "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 — credential.bad_request, credential.not_found, credential.admin_required, credential.encryption_disabled. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

DELETE /api/v1/credentials/{id} ​

Supprimer une connexion

Refusée (409) tant qu’un workflow publié la référence ; details.workflows les nomme. Les comptes OAuth ne se suppriment pas ici mais en déconnectant la boîte.

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

Paramètres

NomOùTypeRequis
idcheminstringoui

Réponses

204 — Supprimé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 — credential.not_found, credential.admin_required, credential.in_use, credential.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/credentials/{id}/test ​

Tester une connexion

Appelle le service tiers avec le secret stocké. Toujours 200 : un jeton révoqué est le résultat, pas une erreur. Restent en erreur HTTP une connexion inconnue (404), un type sans vérificateur (400) et un processus qui n’atteint pas les intégrations (503).

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

Paramètres

NomOùTypeRequis
idcheminstringoui

Réponses

200 — Le verdict.

ChampTypeRequis
okbooleanoui
accountstringnon
codestringnon
statusintegernon
scopesstring[]non
Schéma JSON
json
{
  "type": "object",
  "properties": {
    "ok": { "type": "boolean" },
    "account": { "type": "string", "maxLength": 200 },
    "code": { "type": "string" },
    "status": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "scopes": {
      "maxItems": 20,
      "type": "array",
      "items": { "type": "string", "maxLength": 120 }
    }
  },
  "required": [ "ok" ],
  "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 — credential.not_found, integration.not_testable, integration.not_wired. 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/credentials/{id}/webhook-handshake ​

Lire le jeton de vérification d’un webhook

Le jeton de vérification qu’un service (Notion) a posté une fois à l’URL du déclencheur, à recoller dans son portail. null tant que rien n’a été reçu. Réservé à qui peut modifier la connexion.

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

Paramètres

NomOùTypeRequis
idcheminstringoui

Réponses

200 — Le jeton, ou null.

ChampTypeRequis
tokenstring | nulloui
Schéma JSON
json
{
  "type": "object",
  "properties": { "token": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } },
  "required": [ "token" ],
  "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 — credential.not_found, credential.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.