Documentation Mailzero

Lister les délégations permanentes

Les règles de délégation permanente du propriétaire dans l'ordre : nom, le prédicat de correspondance, le destinataire (une identité d'agent ou un membre de l'espace de travail), le niveau d'autonomie, combien de fois chacune a correspondu. Nécessite assistant:read ; un jeton d'agent est refusé.

Créer une délégation permanente

Transmettre un type d'affaire à un agent ou une personne une fois. match est un prédicat explicite, jamais un appel de modèle : l'un de senderAddress, senderDomain, organisation, workKeyPrefix, senderKind, mailboxIds, labels, subjectPattern (ancré, insensible à la casse), minOccurrences, minConfidence (la probabilité du classifieur calibré sur un label category:, de 0,5 à 1) ; chaque condition énoncée doit être remplie. Les règles sont ordonnées et la première correspondance l'emporte ; le niveau est observe sauf indication contraire. Une règle correspondante transmet le prochain élément correspondant au destinataire, l'en informe par l'avis de délégation, et Today montre pourquoi. Nécessite assistant:write ; un jeton d'agent est refusé.

Modifier une délégation permanente

Renommer, activer ou désactiver, réordonner, changer la correspondance, le destinataire, le niveau ou les autorisations. Abaisser le niveau à observe est l'interrupteur d'arrêt d'urgence d'une règle. Nécessite assistant:write ; un jeton d'agent est refusé.

Supprimer une délégation permanente

Supprime la règle ; les éléments qu'elle a transmis reviennent au propriétaire, les reçus de ce que le destinataire a fait restent. Nécessite assistant:write ; un jeton d'agent est refusé.

Essayer les délégations permanentes sur des faits d'exemple

Un essai à blanc : quelle règle s'appliquerait à un message avec ces faits (boîte mail, clé, expéditeur, objet, étiquettes, occurrences), et pourquoi. Rien ne change. Nécessite assistant:write, un jeton d'agent est refusé.

Tester un effet contre le niveau et les grants d'une délégation permanente

Un essai à blanc de l'ordre de validation pour un effet demandé sous la règle aujourd'hui : le niveau autorise le type ; les grants autorisent les destinataires, le volume (compte des effets exécutés aujourd'hui), l'horaire, la dépense, les classes de risque lues sur l'affaire ; l'approbateur requis a approuvé. Répond le statut qu'un plan prendrait (proposed, approved, escalated ou rejected) avec chaque vérification et pourquoi. Rien ne change. Requiert assistant:write ; un jeton d'agent est refusé.

Lire les métriques de tâches

Les sept nombres de la couche de tâches sur une fenêtre glissante (trente jours par défaut, window_days de 1 à 90), pour le compte et pour chaque délégation permanente : affaires clôturées sans le propriétaire, le temps de l'arrivée à la clôture, les plans exécutés comme proposés, édités et rejetés, les escalations par affaire, les corrections après exécution, les collisions, le coût du modèle par affaire. Lu depuis les receipts, les plans, les escalations et le ledger ; rien n'est estimé. Requiert assistant:read.

Lister la file d'attente des approbations

Les plans en attente du propriétaire (proposés au brouillon, ou retenus par une permission) et les questions posées par les assignés, parmi les dossiers que le lecteur peut voir. Répondre via les interactions de l'élément de travail : approuver ou rejeter un plan, choisir une option ou donner des instructions sur une question. Nécessite assistant:read. Un dossier issu d'un courrier d'authentification avant que ce courrier soit tenu à l'écart de l'assistant s'affiche avec son titre, son résumé, sa demande et les effets de son plan retenus pour un lecteur sans email:auth_secrets.

Énumérer les suggestions de délégation

Les délégations permanentes que l'assistant propose : un sujet qui s'est répété au moins trois fois en quatre-vingt-dix jours (la même organisation ou expéditeur) et a été traité de la même manière à chaque fois (ignoré, répondu, fermé, confié à un agent), avec la règle préremplie. Ouvertes par défaut. Rien n'est créé tant que le propriétaire n'accepte pas. Nécessite assistant:read ; un jeton d'agent est refusé.

Accepter ou rejeter une suggestion de délégation

Accepter : la suggestion se ferme et la règle préremplie revient pour que le client la crée (POST /api/assistant/rules). Rejeter : elle se ferme et ne revient jamais pour les mêmes sujets et traitement. Nécessite assistant:write ; un jeton d'agent est refusé.

Lister les grants attachés aux assignés

Les grants attachés aux agents et membres du propriétaire, en plus de chaque règle qui leur confie des affaires ; le plus strict de la règle et de l'assigné s'applique. Requiert assistant:read ; un jeton d'agent est refusé.

Définir les grants d'un assigné

Attacher des grants à une identité d'agent ou un membre de workspace ; ils remplacent les grants précédents de l'assigné et plafonnent chaque règle qui leur confie des affaires. Requiert assistant:write ; un jeton d'agent est refusé.

Retirer les grants d'un assigné

L'assigné ne garde que ce que chaque règle accorde. Requiert assistant:write ; un jeton d'agent est refusé.

Lire une enveloppe de tâche

L'affaire transmise, telle que l'assigné en a besoin : le résumé avec les preuves, les faits, la délégation (assigné, règle, niveau, les types d'effet autorisés, les grants effectifs), les plans ouverts et récents, le lease. Un token agent lit les affaires qui lui sont transmises et celles des boîtes mail qu'il opère ; le propriétaire lit les siennes. Requiert assistant:read. Un dossier issu d'un courrier d'authentification avant que ce courrier soit tenu à l'écart de l'assistant s'affiche avec son titre, son résumé, sa demande et les effets de son plan retenus pour un lecteur sans email:auth_secrets.

Prendre ou renouveler le lease sur une tâche

Deux assignés ne travaillent jamais une affaire : le lease nomme qui la travaille jusqu'à quand (quinze minutes par défaut, jusqu'à une heure). Le reprendre le renouvelle ; un autre détenteur est refusé avec TASK_LEASED jusqu'à l'expiration. Une demande d'effets prend le lease d'elle-même. Requiert assistant:write.

Rendre le lease

Libère le lease que l'appelant détient ; un lease détenu par un autre assigné est laissé tranquille. Requiert assistant:write.

Demander des effets sur une tâche

L'assigné demande un ou plusieurs effets (reply, forward, label, snooze, resolve, note, request). Le niveau de la délégation décide des types autorisés et les grants les plafonnent : dans les grants à guarded_send ou operate (et les types entrants à triage) les effets s'exécutent immédiatement avec leurs reçus ; à draft ils attendent l'approbation du propriétaire ; un grant échoué escalade au propriétaire ; un type que le niveau n'autorise pas est refusé. La propre demande du propriétaire s'exécute immédiatement. La même clé d'idempotence répond à nouveau avec le premier plan. Requiert assistant:write.

Arrêter et demander au propriétaire

L'assigné pose une question avec les preuves et, lorsque c'est utile, les options qu'il voit. Le propriétaire répond avec les interactions ordinaires de choix ou d'instruction sur la décision que cela crée; l'affaire apparaît dans Today comme nécessitant le propriétaire, le bail est libéré, la tâche attend. Nécessite assistant:write.

Rapporter sur une tâche

Ce que l'assigné a fait et comment cela s'est terminé: done (l'affaire se résout, ou attend lorsqu'une réponse est encore attendue), blocked (le propriétaire est sollicité), ou handed back (le propriétaire reprend la main et la règle reste hors de cette affaire). Les réclamations sont réconciliées avec les reçus que la plateforme a écrits: une réclamation sans reçu est enregistrée comme une réclamation, jamais comme un fait. Le bail est libéré. Nécessite assistant:write.

Lire ce que l'assistant a établi à propos d'un message

Les connaissances que les analyses de ce message ont produites : affirmations (sujet, prédicat, valeur avec type et devise, base, confiance, validité, preuves), entités, engagements et attentes. Rien n'est calculé en cours de route : un message que le pipeline n'a jamais analysé répond analysed: false avec reason (not_enabled quand la boîte mail n'est pas dans l'assistant, not_analysed quand l'analyse n'a pas encore eu lieu). Nécessite assistant:read.

Extraire les champs dont vous avez besoin d'un message avec votre propre schéma

Un appel de modèle sur le texte du message (objet, expéditeur, corps) avec un schéma JSON de l'appelant d'objets et de primitives (jusqu'à 8 Ko, pas de références) : répond data dans cette forme, confidence (0 à 1) et evidence_quotes (extraits textuels). Mis en cache par (message, schéma, instructions) donc la même question coûte un appel (cached: true après). Limité par le budget de modèle du compte (429 quand épuisé, 503 quand la route de modèle est désactivée). Les mails de code de connexion répondent 403 AUTH_MESSAGE. Les corps de plus de 60 000 caractères répondent 413.

Obtenir les paramètres de l'assistant Mailzero

Renvoie l'état d'activation de l'assistant, les indicateurs shadow/pause, la version du consentement, la route de confidentialité, la portée des boîtes mail et toutes les boîtes mail que vous possédez. Nécessite l'autorisation assistant:read.

{
  "enabled": false,
  "shadow_enabled": true,
  "paused": false,
  "mailbox_ids": [
    "mbx_123"
  ],
  "history_window_days": 30,
  "privacy_route": "private_cloud",
  "attachment_vision": false,
  "pipeline_version": "communication-analysis.v1",
  "consent": {
    "required_version": "mailzero-personal-ai.v1",
    "accepted_version": "mailzero-personal-ai.v1",
    "accepted_at": "2026-09-02T09:12:00.000Z"
  },
  "mailboxes": [
    {
      "id": "mbx_123",
      "slug": "hello",
      "domain": "example.com",
      "name": "Hello",
      "kind": "api",
      "address": "hello@example.com"
    }
  ]
}

Mettre à jour les paramètres de l'assistant Mailzero

Active, met en pause, reprend ou délimite explicitement le traitement de l'assistant. Envoyer mailbox_ids: [] désactive toutes les boîtes mail et annule un import d'historique en cours. La reprise nécessite la version actuelle du consentement. La réception du courrier reste indépendante. Nécessite l'étendue assistant:write.

{
  "ok": true,
  "enabled": true,
  "shadow_enabled": true,
  "paused": false,
  "mailbox_ids": [
    "mbx_123"
  ]
}

Consentir et démarrer un import d'historique en arrière-plan

Enregistre le consentement IA explicite actuel, active le traitement en arrière-plan sur les boîtes mail sélectionnées appartenant à l'utilisateur et crée un import d'historique récent reprenables. Le client peut se fermer immédiatement et interroger GET /api/assistant/backfill. Nécessite l'étendue assistant:write.

{
  "ok": true,
  "preview": {
    "mailbox_ids": [
      "mbx_123"
    ],
    "history_window_days": 30,
    "scanned": 0,
    "enqueued": 0,
    "capped": false,
    "background": true,
    "backfill_id": "bf_456"
  }
}

Obtenir la progression de l'import d'historique en arrière-plan

Renvoie la phase de scan/analyse, les messages traités et totaux, le pourcentage, l'ETA adaptatif, l'état de pause et si l'application peut se fermer. Nécessite l'autorisation assistant:read.

{
  "backfill": {
    "id": "bf_456",
    "status": "processing",
    "phase": "analysis",
    "paused": false,
    "processed": 12,
    "total": 40,
    "failed": 0,
    "percent": 30,
    "estimated_seconds_remaining": 240,
    "estimated_completion_at": "2026-09-02T09:20:00.000Z",
    "can_close_app": true,
    "started_at": "2026-09-02T09:12:00.000Z",
    "completed_at": null
  }
}

Réessayer les messages d'import d'historique échoués

Remet en file d'attente les échecs terminaux de l'import le plus récent pour les boîtes mail qui restent activées pour l'IA. Les tentatives automatiques ont déjà été épuisées avant qu'un message n'apparaisse ici. Nécessite l'étendue assistant:write.

{
  "ok": true,
  "retried": 2
}

Obtenir la file de décisions ancrées de Today

Renvoie les projections versionnées Now, Needs you, Waiting, Upcoming et Handled récentes avec as_of, lag, coverage et warnings. Chaque élément pointe vers son message source ; rien ici n'envoie de courrier. Nécessite l'autorisation assistant:read. Le courrier d'authentification (codes de connexion, réinitialisations de mot de passe, liens magiques) ne devient jamais un dossier et n'atteint jamais un modèle. Un dossier issu d'un courrier d'authentification avant que ce courrier soit tenu à l'écart de l'assistant s'affiche avec son titre, son résumé, sa demande et les effets de son plan retenus pour un lecteur sans email:auth_secrets.

{
  "type": "today",
  "as_of": "2026-09-02T09:15:00.000Z",
  "projection_lag_ms": 4200,
  "category": null,
  "categories": {
    "partner_inquiry": 1
  },
  "tag": null,
  "tags": {
    "lumenworks": 1
  },
  "sections": {
    "now": [
      {
        "id": "wi_789",
        "version": 3,
        "status": "needs_judgment",
        "title": "Investor update",
        "summary": "Paul needs the August metrics before his 16:00 partner call.",
        "category": "partner_inquiry",
        "tags": [
          "lumenworks"
        ],
        "proposed_tags": [],
        "mailbox": {
          "id": "mbx_123",
          "address": "hello@example.com",
          "name": "Hello"
        },
        "source": {
          "type": "domani-postgres",
          "conversation_id": "conv_1",
          "event_id": "msg_1",
          "revision": 1
        },
        "attention": {
          "level": "now",
          "reason": "Deadline today from a known investor",
          "confidence": "high",
          "deadline": "2026-09-02T16:00:00.000Z"
        },
        "decision": {
          "id": "dec_1",
          "version": 1,
          "status": "open",
          "question": "How do you want to answer Paul?",
          "options": [
            {
              "id": "opt_send",
              "label": "Send current metrics",
              "recommended": true
            },
            {
              "id": "opt_tomorrow",
              "label": "Ask for tomorrow"
            }
          ]
        }
      }
    ],
    "needs_you": [],
    "waiting": [],
    "upcoming": [],
    "handled": []
  }
}

Récupérer un élément Work de l'assistant et le plan actuel exact

Renvoie l'élément Work ancré, sa Decision ouverte et ses options, le plan Action actuel exact, les engagements et attentes ouverts, les interactions et les reçus. Nécessite l'autorisation assistant:read. Un dossier issu d'un courrier d'authentification avant que ce courrier soit tenu à l'écart de l'assistant s'affiche avec son titre, son résumé, sa demande et les effets de son plan retenus pour un lecteur sans email:auth_secrets.

Lire le résumé de situation d'un élément de travail

Un document qu'un agent lit avant d'agir : la situation (statut, attention, récurrence, expéditeur), l'historique jusqu'à présent (chaque courrier, analysé ou non), les faits établis par les analyses (affirmations avec valeur, base et validité, et les entités), les engagements et attentes ouverts avec ce qui est attendu de qui et depuis quand, ce qui est déjà réglé (boucles fermées et accusés de réception), la Décision actuelle avec ses options, une prochaine étape suggérée (l'option recommandée de la Décision quand il y en a une, sinon une règle : une promesse en retard, une attente en retard à relancer, la demande de l'expéditeur à laquelle répondre), et les messages de preuve. Déterministe et peu coûteux : aucun appel de modèle. Les tokens d'agent lisent les éléments des boîtes aux lettres qu'ils opèrent et les éléments qui leur sont remis.

Lire le résumé de situation pour un correspondant

Ce qu'il faut savoir avant de répondre à une personne : le résumé de leur élément de travail actif le plus récent parmi les boîtes aux lettres que vous pouvez lire (ou une boîte aux lettres), les autres éléments dont ils sont responsables, et leurs dix derniers courriers. brief est null quand rien n'a encore été analysé de leur part.

Lire les faits derrière un élément Work

Les affirmations et entités fusionnées de chaque analyse de l'élément (le plus récent gagne en premier), plus ses engagements et attentes stockés avec leur statut. Les jetons d'agent lisent les éléments des boîtes mail qu'ils opèrent et les éléments qui leur sont remis.

Marquer un élément Work comme ouvert

Enregistre que le propriétaire a ouvert cet élément Work dans sa version actuelle, ce qui retire son marqueur non lu jusqu'à ce que l'élément change à nouveau. Nécessite l'étendue assistant:write.

Ce que l'assistant a appris sur vous

Les règles de silence que l'assistant propose après que le même expéditeur ou la même organisation a été ignoré à chaque retour, les mises en sourdine en vigueur (un expéditeur, un domaine ou une situation que l'assistant tient hors d'Aujourd'hui), chacune avec sa raison, et les étiquettes confirmées une fois, chacune appliquée au prochain dossier du même projet sans question. Acceptez une règle de silence via l'endpoint suggestions ; oubliez une mise en sourdine avec l'endpoint mutes, une étiquette avec l'endpoint tags.

Oublier une mise en sourdine

Le prochain mail de cet expéditeur, domaine ou situation redevient un item.

Oublier une étiquette

Plus rien n'est appliqué sans question : le prochain dossier de ce projet propose à nouveau l'étiquette. Les dossiers qui la portent la gardent.

Enquêter sur une affaire : ce que disent le registre et les liens

Lit, à cet instant, les faits que l'infrastructure publique détient sur le domaine de l'expéditeur (sa date d'enregistrement et son registraire, sa posture SPF et DMARC, s'il reçoit du courrier), où chaque lien du message source va réellement (les redirections suivies un saut à la fois, l'hôte final et les faits du domaine de celui-ci), et ce que chaque pièce jointe est réellement (ses premiers octets par rapport au nom et au type déclaré). Répond le dossier avec les signaux que les faits ajoutent (un domaine enregistré il y a quelques jours, un lien qui atterrit ailleurs, un domaine d'expéditeur qui ne protège rien, un programme nommé comme un document). Aucun fournisseur, aucun compte, rien de stocké; une recherche qui échoue est un fait en soi.

Qui est derrière une affaire : l'organisation, les personnes impliquées, l'historique

Répond la fiche expéditeur d'une affaire : l'organisation de l'expéditeur telle que le profil de domaine stocké la connaît (nom, raison sociale, catégorie, site web, date d'enregistrement, posture de messagerie ; null pour un domaine de messagerie partagé comme gmail.com ou un domaine jamais analysé, et jamais une analyse en direct), les personnes que les messages de l'histoire portent dans from, to et cc avec leurs rôles et si elles appartiennent à la même organisation (les propres boîtes du lecteur exclues), et la relation : combien de courrier est venu de cette adresse à travers les boîtes du lecteur (compté jusqu'à 50), quand pour la première et la dernière fois, les autres affaires de l'expéditeur et les affaires soulevées par des collègues du même domaine. Requiert le scope assistant:read.

Enregistrer une Decision humaine verrouillée par version

Choisir une option, donner une instruction, prendre le contrôle, mettre en veille, ignorer, corriger, signaler le verdict de confiance (phishing ou légitime), ou approuver ou rejeter un plan en attente (un plan approuvé s'exécute immédiatement, avec ses reçus dans la réponse). L'appel est clôturé par work_item_version et rejoué de manière idempotente par idempotency_key. Choisir ou instruire prépare un brouillon exact qui passe toujours par le flux de réponse normal ; ce endpoint n'envoie jamais de courrier. Nécessite le scope assistant:write.

Obtenir l'aperçu exact de l'action par ID opaque

Renvoie l'identité de réponse exacte, les destinataires, le corps, les engagements et les effets secondaires d'un plan d'action préparé, ainsi que son expiration et sa révision source, afin qu'un client puisse montrer ce qui se passera avant que l'utilisateur n'envoie via le endpoint de réponse existant avec assistant_plan_id. Nécessite l'étendue assistant:read.

Obtenir l'activité de l'assistant avec contenu minimisé

Liste les interactions et reçus récents attribués à l'appelant sans les corps de message. Nécessite l'étendue assistant:read.

Exporter les données dérivées de l'assistant

Exporte les analyses, faits acceptés, décisions, interactions, reçus et utilisation du modèle sous forme de pièce jointe JSON. N'inclut jamais les corps d'email source ni les octets des pièces jointes. Nécessite le scope assistant:write. Il faut aussi email:auth_secrets (403 INSUFFICIENT_SCOPE sinon) : l'état dérivé peut contenir ce que l'assistant a tiré du courrier d'authentification avant que ce courrier n'en soit écarté.

Supprimer les données dérivées de l'assistant

Supprime de manière idempotente l'intelligence dérivée, les tâches, l'utilisation du modèle, les appareils, les importations et les paramètres tout en préservant le courrier source. Nécessite l'étendue assistant:write.

{
  "ok": true,
  "deleted": {
    "work_items": 12,
    "claims": 40,
    "entities": 9,
    "jobs": 52
  },
  "source_mail_deleted": false
}

Enregistrer un appareil pour les alertes Now masquées

Enregistre ou fait pivoter un jeton push chiffré pour une installation d'application et un environnement. Seule l'application native appelle ceci; nécessite un assistant actif et l'autorisation assistant:write.

Révoquer un enregistrement d'appareil

Révoque tous les enregistrements push d'une installation, par exemple lors de la déconnexion. Nécessite l'étendue assistant:write.

Vérifier l'état du DNS des e-mails (MX, SPF, DMARC, DKIM)

Vérifie la configuration DNS de la messagerie pour un domaine : enregistrements MX, SPF, DMARC et DKIM. Détecte automatiquement le fournisseur de messagerie à partir des enregistrements MX (Google Workspace, Proton, Fastmail).

{
  "domain": "mysite.com",
  "provider": "google-workspace",
  "mx": {
    "configured": true,
    "records": [
      "1 aspmx.l.google.com",
      "5 alt1.aspmx.l.google.com"
    ]
  },
  "spf": {
    "configured": true,
    "value": "v=spf1 include:_spf.google.com ~all"
  },
  "dmarc": {
    "configured": true,
    "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@mysite.com"
  },
  "dkim": {
    "configured": true,
    "selectors": [
      "google"
    ]
  }
}

curl https://domani.run/api/domains/mysite.com/email/check \
  -H "Authorization: Bearer domani_sk_xxx"

Obtenez l’état de la délivrabilité des e-mails à l’échelle du propriétaire

Sépare la préparation à l’authentification déterministe, les résultats d’acheminement pondérés par destinataire sur 30 jours, l’état de sécurité du compte et le placement mesuré par fournisseur. Le score de préparation n’est pas une probabilité d’arrivée en boîte de réception, et un placement non mesuré est renvoyé comme not_tested.

curl https://domani.run/api/domains/mysite.com/email/deliverability \
  -H "Authorization: Bearer domani_sk_xxx"

Configurer la messagerie sur un domaine

Préconfigurez le DNS de messagerie sur un domaine (facultatif). Ceci est appelé automatiquement par create_mailbox en cas de besoin. Passez force=true pour remplacer le fournisseur de messagerie existant (Google Workspace, Fastmail, Proton).

Supprimer l'e-mail d'un domaine

Supprimez le courrier électronique d'un domaine, supprimez toutes les boîtes aux lettres et tous les messages, puis définissez emailEnabled sur false. Cela modifie le courrier de tout le domaine : un jeton confiné à des boîtes aux lettres reçoit donc 403 MAILBOX_CONFINED.

Vérifier l'état DNS du courrier électronique

Vérifiez l'état de vérification DNS des e-mails pour un domaine. Indique si le domaine est vérifié et prêt, les détails de l'enregistrement DNS et le nombre de boîtes aux lettres.

Créer une boîte mail sur domani.run

Créez une adresse e-mail gratuite sur domani.run (par exemple hello@domani.run). Aucune propriété de domaine requise. Limité à 1 boîte mail @domani.run gratuite par utilisateur. De nombreuses limaces communes sont réservées.

Lister toutes les boîtes aux lettres

Répertorier toutes les boîtes aux lettres auxquelles l’identité appelante peut accéder sur l’ensemble des domaines, y compris grâce aux autorisations de l’espace de travail.

Créer une boîte aux lettres

Créez une adresse e-mail (boîte aux lettres). Fournissez une adresse complète telle que "hello@mysite.com". Le DNS de messagerie est automatiquement configuré lors de la première utilisation. Passez force=true pour remplacer un fournisseur de messagerie existant. La capacité de la boîte aux lettres du domaine personnalisé est déterminée par le compte actif ou le plan d'espace de travail. Chaque compte peut créer une boîte aux lettres @domani.run gratuite séparément avec POST /api/email. Transmettez workspace_id pour créer la boîte aux lettres dans un espace de travail que vous possédez. Pour un domaine personnalisé, cela adopte explicitement et atomiquement le domaine et toutes ses boîtes aux lettres sœurs non délimitées dans cet espace de travail ; un domaine ne peut jamais être divisé en plusieurs espaces de travail. Passez kind="hosted" pour créer une véritable boîte aux lettres IMAP/SMTP sur votre propre domaine (connectez Apple Mail, Thunderbird ou n'importe quel client) au lieu de la boîte aux lettres API par défaut (envoyer/recevoir via API + webhooks). Les boîtes aux lettres hébergées renvoient des enregistrements DNS à publier, les paramètres du client de messagerie et un mot de passe d'application à usage unique. Nécessite un domaine que vous possédez.

Lister toutes les boîtes aux lettres

Répertorier toutes les boîtes aux lettres auxquelles l’identité appelante peut accéder, y compris grâce aux autorisations de l’espace de travail. Identique à GET /api/email.

Obtenir les détails de la boîte aux lettres

Obtenez des détails sur une boîte aux lettres spécifique grâce à son adresse e-mail complète (codée en URL, par exemple hello%40mysite.com).

Mettre à jour la boîte aux lettres

Mettez à jour le nom d’affichage d’une boîte aux lettres, l’URL du webhook ou l’adresse e-mail de transfert par son adresse e-mail complète. Définissez sur null pour désactiver/effacer.

Supprimer une boîte aux lettres

Supprimez une boîte aux lettres par son adresse e-mail complète. Nécessite confirm=true dans le corps. Sans confirmation, renvoie un aperçu avec message_count.

Envoyer un email

Envoyez un e-mail depuis une boîte identifiée par son adresse complète. Le serveur exécute d’abord une politique versionnée obligatoire : les échecs objectifs de sécurité sont refusés, tandis que les problèmes de réputation et de qualité du contenu sont renvoyés comme avertissements. Pour une réponse collaborative dans un fil, transmettez le bail de composition, la valeur reply_version observée et une clé d’idempotence stable ; le serveur rejette atomiquement les réponses périmées ou doubles juste avant l’envoi. Maximum 20 destinataires uniques par message. Limite : 100 destinataires par heure et par boîte.

Contrôler en amont un e-mail sortant

Exécutez la stratégie côté serveur versionnée exacte utilisée par le point de terminaison d’envoi sans envoyer ni consommer de quota de courrier électronique. Les liens d'authentification HTTPS publics sur des domaines tiers sont autorisés avec un avertissement de réputation. Les URL locales/privées, les liens d'authentification non HTTPS et les pièces jointes exécutables sont bloqués ; les corps au-dessus de 102 Ko produisent un avertissement d'écrêtage.

Liste des e-mails

Répertoriez les e-mails dans un dossier canonique ou une vue virtuelle. La valeur par défaut est Boîte de réception. L'emplacement du dossier est indépendant de la direction du message et du verdict de spam. Le courrier d'authentification (OTP/codes de vérification, réinitialisations de mot de passe, liens magiques) est étiqueté security: "auth" ». Les jetons sans portée email:auth_secrets voient les messages avec le sujet et le corps MASQUÉS (redacted: true) - les métadonnées (de, date) restent visibles. Les filtres subject, q et attachments portent sur ce que l'appelant peut lire : sans la portée, un tel message ne correspond que par son sujet et son corps masqués, et une recherche du code qu'il contient ne trouve donc rien.

Rechercher des emails par sens et par mots

Recherche dans les boîtes mail que vous pouvez lire, ou dans une boîte mail avec mailbox. Hybride par défaut : l'embedding du message (pgvector, cosine) et l'index de mots pondérés sont fusionnés par rang réciproque avec un léger boost de récence, en une seule instruction ; why indique quelle branche a correspondu. Opérateurs Gmail dans q : from: to: cc: subject: label: filename: mailbox: is:unread|read|starred|unstarred has:attachment in:inbox|archive|sent|spam|trash|anywhere after:2026/08/01 before: newer_than:7d older_than:2w (h/d/w/m/y), "a phrase", -word ou -from: pour exclure, a OR b. Une requête faite uniquement d'opérateurs liste les messages correspondants du plus récent au plus ancien (why: filter). Les codes et liens de connexion, le spam et les emails système ne sont jamais indexés ; les boîtes mail listées dans search_opt_out_mailbox_ids de l'assistant sont recherchées par mots uniquement. Un token lié à une identité d'agent recherche uniquement dans les boîtes mail que son agent exploite. Nécessite email:read. Sans email:auth_secrets, le courrier d'authentification entrant est écarté avant le classement : aucun mot, opérateur ou filtre ne le trouve, et la recherche d'un code de connexion ne trouve donc rien.

curl "https://domani.run/api/emails/search?q=facture+tucows+ao%C3%BBt&limit=5" \
  -H "Authorization: Bearer domani_sk_xxx"

Commencer à connecter une boîte de réception Gmail

Retourne l'URL de consentement Google liée à votre compte et à la limite d'importation. Ouvrez-la dans un navigateur ; après consentement la boîte de réception devient une boîte mail connectée à sa propre adresse, le courrier reçu après la limite est importé (par défaut : les dernières 24 heures), et le nouveau courrier suit au fur et à mesure qu'il arrive. Jamais toute la boîte de réception : élargissez plus tard avec POST /api/emails/{address}/import. Nécessite email:write. Google OAuth doit être configuré sur le serveur.

Commencer à connecter une boîte de réception Outlook

Renvoie l'URL de consentement Microsoft liée à votre compte et à la borne d'importation. Ouvrez-la dans un navigateur ; après consentement, la boîte de réception devient une boîte mail connectée à sa propre adresse, le courrier reçu après la borne est importé (par défaut : les dernières 24 heures), et le nouveau courrier suit au fur et à mesure qu'il arrive. Jamais la boîte de réception entière : élargissez plus tard avec POST /api/emails/{address}/import. Nécessite email:write. Microsoft OAuth doit être configuré sur le serveur.

Énumérer les façons dont une boîte de réception peut être connectée

Une ligne par fournisseur (Gmail, Outlook, toute boîte de réception par transfert, une adresse hébergée ici) : comment la connexion démarre (un écran de consentement, une règle de transfert, une adresse créée), ce que la connexion peut faire (lire, ou lire et écrire), si elle importe les anciens mails, et si ce serveur est configuré pour cela. Afficher un bouton de connexion uniquement quand configured est true ; reason nomme la variable manquante pour l'opérateur. Nécessite email:read.

Connecter une boîte de réception par transfert

Crée une boîte mail connectée à l'adresse propre de la boîte de réception et répond avec une adresse de transfert sur le domaine de transfert de la plateforme, avec les étapes pour Gmail, Outlook et d'autres fournisseurs. Ajoutez une règle de transfert chez le fournisseur ; ce qui arrive à cette adresse est déballé (expéditeur original, date, objet) et stocké sous la boîte mail connectée. Gmail demande à l'adresse de transfert de confirmer : le code et le lien apparaissent sur la connexion. Le premier mail qui revient, ou une sonde (POST /api/emails/{address}/connector/verify), rend la connexion active. Seul le nouveau courrier arrive de cette façon ; l'ancien courrier ne peut pas être importé. Nécessite email:write. Le domaine de transfert doit être configuré sur le serveur.

Envoyer une sonde à travers la règle de transfert

Envoie un mail à la boîte de réception connectée ; lorsque la règle de transfert le ramène à l'adresse de transfert, la connexion devient active. Uniquement pour une connexion par transfert. Nécessite email:write.

Lire la connexion d'une boîte mail connectée

Type, statut, la limite d'importation, la phase de synchronisation (l'analyse d'importation, puis historique), la progression de l'importation (analysés, copiés, à analyser, analysés), la dernière synchronisation et la dernière erreur. Nécessite email:read. La confirmation de transfert (le code et le lien de Gmail) est du courrier d'authentification : sans email:auth_secrets, son code et son url valent null et elle porte redacted: true. Un jeton confiné à des boîtes aux lettres ne trouve que ses propres boîtes aux lettres (404 sinon).

Déconnecter une boîte mail connectée

Supprime les propres copies de la personne (messages, pièces jointes, lignes de recherche, tâches en attente) et le credential ; conserve la ligne de boîte mail, le lien marqué déconnecté, et ce que les agents ont fait (receipts). Seule une boîte mail connectée peut être déconnectée. Nécessite email:write.

Importer du courrier plus ancien d'une boîte mail connectée

Élargit l'importation à une date antérieure : une nouvelle exécution d'importation copie le courrier entre la nouvelle limite et l'actuelle, dans l'ordre d'arrivée, sous son propre plafond de coût. Refusé pendant qu'une analyse d'importation est encore en cours. Nécessite email:write.

Rechercher dans une boîte mail par sens et par mots

La même recherche que GET /api/emails/search, restreinte à cette boîte mail. Nécessite email:read. Sans email:auth_secrets, le courrier d'authentification entrant est écarté avant le classement : aucun mot, opérateur ou filtre ne le trouve, et la recherche d'un code de connexion ne trouve donc rien.

Lister les conversations d'une boîte mail

Messages regroupés comme les clients mail les regroupent : une réponse rejoint le fil du message auquel elle répond (In-Reply-To, puis la chaîne References), un mail sans en-têtes utilisables rejoint le fil le plus récent avec le même sujet et un correspondant en commun dans les trente jours, tout le reste démarre un fil dont l'id est l'id de son premier message. Les fils sont ordonnés par dernière activité ; la corbeille et le spam ne participent jamais sauf s'ils sont nommés comme dossier. folder=inbox|archive|sent garde les fils qui ont un message là mais compte toujours la conversation entière.

Lire une conversation, message le plus ancien en premier

Tous les messages du fil (corbeille incluse, donc rien ne manque de l'histoire) avec leur texte, le plus ancien en premier, plus les participants et le nombre de non lus. Le mail d'authentification est caviardé comme le sont les lectures de messages.

Diffuser les événements de la boîte mail (server-sent events)

Répond text/event-stream. Sans curseur, le flux démarre au présent ; avec since (un curseur provenant de /api/email/changes ou l'id de n'importe quel événement antérieur), il rejoue d'abord chaque changement après ce point, puis suit le journal de la boîte mail en direct : chaque trame porte le type du changement comme nom d'événement (message.received, message.updated, message.deleted, message.moved, message.status, mailbox.resync_required, assistant.item.delegated, assistant.item.recalled, ...), le changement comme données JSON avec son cursor reprennable, et ce même curseur comme id de trame. La première trame est ready avec le curseur à partir duquel reprendre ; un commentaire keep-alive arrive toutes les 20 secondes ; la connexion se ferme après environ 5 minutes avec une trame close et un indice retry:. Reconnectez avec Last-Event-ID (ou since) pour reprendre sans écart et sans doublon. Les jetons d'agent sont confinés aux boîtes mail que l'agent opère. Une entrée concernant un élément de travail issu d'un courrier d'authentification porte son title et son ask masqués pour un jeton sans email:auth_secrets.

Répertorier les dossiers de courrier électronique et les comptes

Renvoie les décomptes dérivés du serveur pour les dossiers système et les vues virtuelles, ainsi que les fonctionnalités de cycle de vie pour le backend de la boîte aux lettres.

Appliquer une action de cycle de vie aux messages

Déplacez, restaurez, marquez comme lu, ajoutez une étoile ou supprimez définitivement jusqu'à 100 ID de message explicites. Le déplacement vers la corbeille est réversible. La suppression permanente nécessite email:delete et n'accepte que les messages déjà dans la corbeille. Chaque réponse est un reçu d'opération durable avec un résultat par ID demandé. Fournissez une clé stable dans l'en-tête standard Idempotency-Key ou dans le champ JSON hérité idempotency_key et réutilisez-la après les délais d'attente ; une nouvelle tentative exacte renvoie le reçu stocké sans autre mutation. Si les deux formulaires sont fournis, ils doivent correspondre. La réutilisation d'une clé avec une requête différente renvoie 409. En cas d'omission, le serveur crée une clé et la renvoie dans le corps et l'en-tête Idempotency-Key. Renvoie 207 lorsque seule une partie du lot réussit.

Marquer les messages comme lus ou non lus

Point de terminaison de compatibilité pour les mises à jour de l’état de lecture sécurisées et réessayées. Renvoie le reçu canonique d’opération durable par article plus le nombre hérité. Fournissez et réutilisez l'en-tête Idempotency-Key ou le champ de compatibilité idempotency_key après les délais d'attente.

Supprimer des messages en masse

Point de terminaison de compatibilité qui déplace les messages en toute sécurité vers la corbeille. Renvoie le reçu canonique d’opération durable par article plus le nombre hérité. Fournissez et réutilisez l'en-tête Idempotency-Key ou le champ de compatibilité idempotency_key après les délais d'attente.

Recevoir un message

Récupérez un seul message par identifiant à partir d'une boîte aux lettres identifiée par son adresse e-mail complète. Les messages classés comme courrier d'authentification (OTP, réinitialisation du mot de passe, lien magique) reviennent avec le sujet/corps masqué, sauf si le jeton a la portée email:auth_secrets.

Supprimer un message

Déplacez un message vers la corbeille. Ceci est réversible. Utilisez l'action de cycle de vie avec delete_permanently et un jeton email:delete pour effacer un message déjà dans la corbeille.

Répondre à un message

Répondez à un message dans une boîte identifiée par son adresse complète. Les en-têtes de fil sont renseignés automatiquement, et l’original est cité sous la réponse comme le font les clients de messagerie (ligne d’attribution dans la langue du compte, lignes > dans le texte, bloc gmail_quote dans le HTML), sauf si quote vaut false. Les clients collaboratifs doivent transmettre le bail de composition, la valeur reply_version observée et une clé d’idempotence stable ; le serveur rejette atomiquement une réponse périmée ou double juste avant l’envoi.

Transférer un message

Transférer un message d'une boîte aux lettres identifiée par son adresse e-mail complète vers un autre destinataire. Le transfert du courrier d'authentification (OTP, réinitialisation du mot de passe, lien magique) nécessite la portée email:auth_secrets - cela exfiltrerait le secret.

Obtenir des informations sur l'avatar de la boîte aux lettres

Renvoie l'URL Gravatar (si définie) et le lien d'inscription pour une boîte aux lettres identifiée par son adresse e-mail complète.

Obtenir la configuration du webhook de la boîte aux lettres

Renvoie l'URL du webhook, le secret de signature, les noms d'en-tête d'authentification configurés et l'état d'une boîte aux lettres. Les valeurs d'en-tête ne sont jamais renvoyées.

Définir un webhook de boîte aux lettres

Configurez la destination HTTPS des événements de boîte aux lettres signés HMAC : le courrier entrant par défaut, plus (sur abonnement via events) le verdict de distribution du courrier envoyé DEPUIS la boîte aux lettres - un rebond atteint l'expéditeur quelques secondes après l'acceptation de l'envoi, au lieu de ne vivre que dans l'historique du message. Les distributions entrantes en direct sont stockées de manière durable, tentées immédiatement et réessayées jusqu'à trois fois. Chaque tentative inclut X-Domani-Delivery-Attempt commençant à 1. Les valeurs facultatives d'autorisation ou de X-API-Key sont chiffrées et ne sont jamais renvoyées ; les opérateurs humains doivent les soumettre en dehors du contexte du modèle via les options de variable d'environnement CLI.

curl -X PUT https://domani.run/api/emails/agent%40example.com/webhook \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://agent.example/webhook","events":["email.received","email.bounced","email.delivered"]}'

Supprimer le webhook de la boîte aux lettres

Supprimez l'URL du webhook et le secret de signature d'une boîte aux lettres. Les e-mails entrants seront uniquement stockés.

Faire pivoter le secret de signature du webhook

Régénérez le secret de signature HMAC-SHA256 pour un webhook de boîte aux lettres. Le vieux secret est immédiatement invalidé.

Tester le webhook de la boîte aux lettres

Envoyez une charge utile de test signée à l’URL du webhook de la boîte aux lettres. Renvoie l'état HTTP et si la distribution a réussi. Les tests ne sont pas retentés ; les distributions entrantes en direct sont réessayées jusqu'à trois fois.

Répertorier les alias de boîtes aux lettres

Répertoriez toutes les adresses alias qui acheminent les messages vers une boîte aux lettres. Les alias permettent à plusieurs adresses (sales@, hello@, contact@) de partager une boîte de réception sans utiliser d'emplacement de boîte aux lettres.

Ajouter un alias de boîte aux lettres

Ajoutez une adresse alias qui livre dans cette boîte aux lettres sans utiliser d’emplacement supplémentaire. L’alias doit appartenir au même domaine que la boîte aux lettres. Fournissez un simple slug ('sales') ou une adresse complète ('sales@mysite.com').

Supprimer un alias de boîte aux lettres

Supprimez un alias d'une boîte aux lettres. Les e-mails envoyés à cette adresse ne sont plus envoyés.

Obtenir les paramètres du client de messagerie (hébergé)

Obtenez les paramètres de connexion IMAP/SMTP pour une boîte aux lettres hébergée, pour configurer Apple Mail, Thunderbird ou tout autre client de messagerie. Le nom d'utilisateur est l'adresse complète ; le mot de passe est un mot de passe d'application (créez-en un avec POST /api/emails/{address}/credentials). Boîtes aux lettres hébergées uniquement.

Répertorier les mots de passe des applications (hébergées)

Répertoriez les mots de passe d'application pour une boîte aux lettres hébergée. Les secrets ne sont affichés qu'une seule fois lors de la création ; cela renvoie uniquement les étiquettes et les métadonnées. Boîtes aux lettres hébergées uniquement.

Créer un mot de passe d'application (hébergé)

Créez un mot de passe d'application pour une boîte aux lettres hébergée, utilisé comme mot de passe dans un client de messagerie (IMAP/SMTP). Le secret est renvoyé une fois - stockez-le maintenant. Boîtes aux lettres hébergées uniquement.

Révoquer le mot de passe d'une application (hébergée)

Révoquer le mot de passe d'une application. Tout client de messagerie qui l'utilise cesse immédiatement de se connecter. Boîtes aux lettres hébergées uniquement.

Signaler un message à un humain

Escalader un message vers l’humain du compte (ou retirer le signalement avec clear=true). Définit needs_human sur le message, maintient sa conversation dans le statut needs_human et déclenche le webhook email.escalated + une notification dans l’application. La primitive produit derrière 'answer the easy ones, stop on the one the human must decide'.

Définir un rappel de relance

Définir (ou effacer avec clear=true) un rappel de relance unique sur un message. Lorsque remind_at arrive et que le message est toujours sans réponse (entrant : aucune réponse envoyée ; sortant : aucune réponse entrante reçue), email.reminder_due se déclenche sous forme de webhook + notification dans l’application et le rappel s’efface de lui-même.

Répertorier les contacts

Le carnet d’adresses du compte, alimenté automatiquement par le trafic de courrier : correspondants, nombre de messages, dernière activité et notes. Par défaut, les plus récemment actifs en premier (order=recent), pour l’affichage : un contact qui reçoit un nouveau courrier pendant un parcours paginé passe devant le curseur, et ce parcours peut donc le manquer. Pour synchroniser tout le carnet, passez order=created : les plus anciens en premier par date de création puis par id, une clé qui ne change jamais ; chaque contact présent pendant tout le parcours revient donc exactement une fois, et les contacts créés entre-temps arrivent à la fin. Un curseur ne poursuit que l’ordre dont il provient (400 INVALID_CURSOR sinon). Agrège les données de toutes les boîtes aux lettres ; les jetons confinés à une boîte aux lettres sont donc refusés (400 MAILBOX_CONFINED).

Créer ou mettre à jour un contact

Enregistrer un contact : définir un nom d’affichage et joindre des notes ('prefers short emails', 'decision maker at Acme'). Le trafic de courrier continue d’alimenter le nombre de messages dans tous les cas.

Supprimer un contact

Supprimer un contact du carnet d’adresses. Le trafic de courrier le recréera comme contact automatique s’il écrit à nouveau.

Répertorier les règles de courrier entrant

Répertoriez les règles de filtrage entrant d'une boîte aux lettres, dans l'ordre de priorité dans lequel elles sont appliquées (la première correspondance gagne).

Ajouter une règle de courrier entrant

Ajoutez une règle exécutée sur les messages entrants correspondant à un champ (from/to/subject/body). Actions : drop, mark_read, forward (action_arg = adresse), webhook_only (ignorer le transfert) et label (action_arg = libellé). Les règles s’appliquent par priorité croissante ; la première correspondance l’emporte.

Supprimer une règle de courrier entrant

Supprimez une règle de filtrage entrant d’une boîte aux lettres.

Définir un domaine fourre-tout

Acheminez chaque e-mail envoyé à une adresse sans correspondance sur le domaine vers une boîte aux lettres désignée. Tout ce qui ne correspond pas à une boîte aux lettres, une sous-adresse ou un alias se retrouve dans le fourre-tout. La boîte aux lettres doit déjà exister sur le domaine. Cela modifie le courrier de tout le domaine : un jeton confiné à des boîtes aux lettres reçoit donc 403 MAILBOX_CONFINED.

Effacer le domaine fourre-tout

Supprimez le fourre-tout sur un domaine. Les e-mails adressés à des adresses sans correspondance seront à nouveau supprimés. Cela modifie le courrier de tout le domaine : un jeton confiné à des boîtes aux lettres reçoit donc 403 MAILBOX_CONFINED.

Synchroniser progressivement une boîte aux lettres

Appelez sans curseur pour capturer une ligne de base avant un instantané complet délimité. Passez ensuite next_cursor pour rejouer les mutations qui se sont produites pendant et après cet instantané. Les curseurs sont opaques, signés, liés à une boîte aux lettres et expirent après 30 jours. Les notifications push ne sont que des indices d'invalidation ; ce journal est la source de récupération durable. Une entrée concernant un élément de travail issu d'un courrier d'authentification porte son title et son ask masqués pour un jeton sans email:auth_secrets.

Liste des adresses supprimées

Répertoriez les adresses de votre liste de suppression : rebonds définitifs et plaintes (intégrés automatiquement à partir des événements d’acheminement), ainsi que les entrées manuelles. Les envois à ces adresses sont ignorés. Pagination par curseur.

Ajouter une suppression

Ajoutez manuellement une adresse à votre liste de suppression afin que les futurs envois l'ignorent. Les rebonds durs et les plaintes sont ajoutés automatiquement ; utilisez-le pour les adresses auxquelles vous ne souhaitez plus envoyer d'e-mails. Idempotent.

Supprimer une suppression

Supprimez une adresse de votre liste de suppression afin de pouvoir l'envoyer à nouveau par e-mail (par exemple après que le destinataire ait corrigé sa boîte aux lettres).

Demander un transfert de propriété d'un espace de travail

Propriétaire uniquement. Envoie un lien d’acceptation de 48 heures à un membre existant. Rien ne bouge jusqu'à ce que ce membre authentifié accepte.

Révoquer un transfert de propriété en attente

Accepter la propriété de l'espace de travail

Cible uniquement. Transfère atomiquement l’espace de travail, les domaines étendus et les boîtes aux lettres ; l'ancien propriétaire devient administrateur et le payeur existant reste inchangé.

Créer un nouveau compte

Commence la création d'un nouveau compte (ou connecte un compte existant) en envoyant un lien de connexion par e-mail ; aucune clé d'API n'est renvoyée ici. Une personne qui clique sur ce lien dans un navigateur arrive sur le tableau de bord déjà connectée. Une CLI ou un agent sans session de navigateur doit utiliser à la place le flux de connexion par appareil (POST /api/auth/cli puis interroger GET /api/auth/cli/poll), qui envoie par e-mail la même approbation et renvoie une clé d'API une fois approuvée - la réponse l'indique dans next_steps. Passer un code ref lie de façon permanente le nouvel utilisateur à un parrain - le parrain gagne une commission sur tous les futurs achats de domaines de cet utilisateur.

{
  "ok": true,
  "verification_required": true,
  "message": "Check your email for a sign-in link to finish creating your account.",
  "hint": "A human must open that email and click the link in a browser to finish verification; no API key is issued yet.",
  "next_steps": [
    "If a person can click the email link, nothing else to do: they land on the dashboard already signed in.",
    "If you are a CLI or agent without a browser session, start a device-login flow instead: POST /api/auth/cli, then poll GET /api/auth/cli/poll?code=... until status is \"complete\" - the same email approves it and hands back an API key, no browser needed on your side."
  ]
}

curl -X POST https://domani.run/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com"}'

Envoyer un e-mail de connexion avec un lien magique

Envoie un lien de connexion à l’e-mail fourni. Si l'utilisateur n'existe pas, crée d'abord un compte. Le lien magique redirige vers le tableau de bord avec les informations d'authentification. Pour l'accès à l'API par programmation, utilisez POST /api/auth/register pour obtenir directement une clé API.

{
  "ok": true,
  "message": "Check your email for a sign-in link."
}

curl -X POST https://domani.run/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com"}'

Vérifier un jeton de lien magique

Valide le jeton de lien magique et redirige vers le tableau de bord avec les informations d'identification d'authentification. Utilisé par l'e-mail de lien magique - généralement non appelé directement par les agents. Les agents doivent plutôt utiliser POST /api/auth/register.

Générer un code de connexion à usage unique entre hôtes

Navigateur uniquement : permet à une personne connectée sur domani.run ou mailzero.run de reprendre sa session sur l’autre hôte sans second lien magique. Renvoie une URL dont le fragment porte un code à usage unique, valable 60 secondes et lié à l’hôte ; ce code n’est jamais journalisé ni envoyé dans une chaîne de requête. Inutile hors d’une session de navigateur, il n’est donc pas exposé comme outil d’agent.

{
  "url": "https://mailzero.run/auth/handoff#code=xxx&next=%2Finbox"
}

Échanger un code de connexion à usage unique entre hôtes

Navigateur uniquement : appelé par la page /auth/handoff sur l’hôte cible pour échanger le code du fragment d’URL contre une session, exactement comme GET /api/auth/verify le fait pour un lien magique. Le code doit correspondre au Host sur lequel cette requête est arrivée. Ce n’est pas un outil d’agent.

{
  "ok": true,
  "next": "/inbox"
}

Obtenir les détails du compte courant

Renvoie les informations du compte de l'utilisateur authentifié, notamment l'e-mail, l'état du paiement, l'état des informations de contact, le code de référence et le nombre d'utilisations. Les agents doivent appeler ceci après l'authentification pour vérifier has_payment_method et has_contact avant de tenter des achats.

{
  "id": "cm5abc123",
  "email": "dev@example.com",
  "plan": "agent",
  "workspace_plans": [
    "mail_pro"
  ],
  "has_payment_method": true,
  "has_contact": true,
  "referral_code": "x7k9m2",
  "referral_rate": 20,
  "domain_count": 3,
  "token_count": 2,
  "created_at": "2025-01-15T10:30:00.000Z"
}

curl https://domani.run/api/me \
  -H "Authorization: Bearer domani_sk_xxx"

Mettre à jour les préférences du compte

Mettez à jour le mode de paiement préféré de l'utilisateur authentifié et/ou les paramètres régionaux BCP 47. Les réponses de l'API restent structurées et ne sont pas traduites.

Supprimer le compte (bloqué pendant que les domaines sont détenus)

Supprimez définitivement le compte, les jetons, les webhooks, les boîtes aux lettres et autres données d'application de l'utilisateur authentifié. Les domaines enregistrés ne sont PAS supprimés avec le compte : la demande échoue avec 409 HAS_DOMAINS jusqu'à ce que chaque domaine soit transféré. Cette action ne peut pas être annulée.

Obtenez un état d'activation véridique et les prochaines actions recommandées

Renvoie les jalons du produit dérivé du serveur et les prochaines actions tenant compte des capacités. La création de jetons, l'utilisation de jetons, les pages vues et l'état de la liste de contrôle du client sont délibérément exclus.

curl https://domani.run/api/me/activation \
  -H "Authorization: Bearer domani_sk_xxx"

Ignorer ou restaurer le guidage de première exécution

Enregistre uniquement les préférences de présentation. Il ne peut pas franchir une étape de produit.

Obtenir les coordonnées des inscrits

Renvoie les coordonnées WHOIS du titulaire pour l'utilisateur authentifié. Facultatives pour un achat (tant qu'elles manquent, le contact de Domani détient les nouveaux domaines pour le compte de l'utilisateur), obligatoires pour un transfert entrant.

{
  "has_contact": true,
  "contact": {
    "first_name": "Jane",
    "last_name": "Doe",
    "address1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US",
    "phone": "+1.2125551234",
    "email": "jane@example.com"
  }
}

curl https://domani.run/api/me/contact \
  -H "Authorization: Bearer domani_sk_xxx"

Définir les coordonnées du inscrit

Définit ou met à jour vos coordonnées WHOIS de titulaire. Facultatives pour un achat, obligatoires pour un transfert entrant. Elles deviennent le contact titulaire et de facturation de vos domaines : tant qu'elles manquent, le contact de Domani les détient pour votre compte. À chaque mise à jour, les nouvelles coordonnées sont envoyées à tous vos domaines actifs chez les bureaux d'enregistrement qui acceptent les changements de contact, ce qui fait de vous leur titulaire ; le bureau d'enregistrement peut vous demander par e-mail de les confirmer sous 15 jours.

curl -X PUT https://domani.run/api/me/contact \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Jane","last_name":"Doe","address1":"123 Main St","city":"New York","state":"NY","postal_code":"10001","country":"US","phone":"+1.2125551234","email":"jane@example.com"}'

Renvoyer la vérification de l'e-mail du contact

Renvoyez l’e-mail de vérification à l’adresse de contact du compte. Limité à un envoi toutes les 15 minutes par adresse.

Lister les appareils connectés

Chaque navigateur, application mobile et terminal connecté au compte, la session de l'appelant en premier (current). Chaque connexion ouvre sa propre session : se connecter sur un nouvel appareil ne déconnecte donc jamais les autres. La localisation est l'endroit d'où l'appareil s'est connecté (pays et ville d'après son IP), absente si elle est inconnue. Les clés API ne sont pas des sessions : listez-les avec GET /api/tokens.

{
  "sessions": [
    {
      "id": "cm5ses123",
      "current": true,
      "kind": "web",
      "product": "domani",
      "device": {
        "type": "desktop",
        "os": "macOS",
        "browser": "Chrome"
      },
      "location": {
        "country": "FR",
        "city": "Paris"
      },
      "signed_in_at": "2026-10-01T10:00:00.000Z",
      "last_active_at": "2026-10-18T09:12:00.000Z"
    },
    {
      "id": "cm5ses456",
      "current": false,
      "kind": "mobile",
      "product": null,
      "device": {
        "type": "mobile",
        "os": "iOS",
        "browser": null
      },
      "location": {
        "country": "FR",
        "city": "Lyon"
      },
      "signed_in_at": "2026-09-20T18:30:00.000Z",
      "last_active_at": "2026-10-17T21:04:00.000Z"
    }
  ],
  "hint": "Sign a device out with DELETE /api/sessions/{id}, or every device but this one with DELETE /api/sessions."
}

curl https://domani.run/api/sessions \
  -H "Authorization: Bearer domani_sk_xxx"

Déconnecter tous les autres appareils

Déconnecte toutes les sessions du compte sauf celle qui fait la requête. Ces appareils devront se reconnecter à leur prochaine requête. Les clés API ne changent pas.

{
  "revoked": 2,
  "hint": "Every other device is signed out. API keys are unchanged."
}

curl -X DELETE https://domani.run/api/sessions \
  -H "Authorization: Bearer domani_sk_xxx"

Déconnecter un appareil

Déconnecte une session. current désigne la session qui fait la requête (se déconnecter ne nécessite aucune portée) ; toute autre session nécessite tokens:write.

{
  "success": true,
  "current": false,
  "hint": "That device is signed out and will be asked to sign in again."
}

curl -X DELETE https://domani.run/api/sessions/cm5ses456 \
  -H "Authorization: Bearer domani_sk_xxx"

Lister les jetons API d'une identité agent

Les jetons liés à cette identité agent (clés masquées, scopes, confinement aux boîtes mail, dernière utilisation). Un jeton lié à un agent est la vue de cet agent sur chaque assistant et surface mail.

Donner à un agent sa propre clé API en un seul appel

Crée un jeton lié à cette identité agent, confiné aux boîtes mail que l'agent opère, avec les scopes minimaux dont un agent a besoin (assistant:read, assistant:write, email:read, email:write). Avec cette clé, l'agent lit uniquement son propre Today, ses boîtes mail et les éléments qui lui sont confiés; nommer un autre agent répond 403 et les routes réservées au propriétaire (settings, backfill, export) le refusent. La clé complète est retournée uniquement dans cette réponse. Requiert tokens:write. Un agent qui n'opère aucune boîte aux lettres ne reçoit aucune portée de courrier par défaut, et les demander répond 400 AGENT_MAILBOXES_REQUIRED : une clé sans boîte aux lettres atteindrait toutes les boîtes aux lettres du compte.

curl -X POST https://domani.run/api/agents/identity/dave/tokens \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Dave on the laptop"}'

Révoquer le jeton API d'un agent

Révoque un jeton lié à cette identité agent. Il cesse de fonctionner immédiatement. Requiert tokens:write.

Listez vos jetons API

Renvoie tous les jetons API pour l'utilisateur authentifié. Les clés sont masquées pour des raisons de sécurité (12 premiers + 4 derniers caractères visibles). Utilisez-le pour auditer les jetons actifs.

{
  "tokens": [
    {
      "id": "cm5abc123",
      "name": "Default",
      "key": "domani_sk_a...wxyz",
      "lastUsed": "2025-02-18T10:30:00.000Z",
      "expiresAt": null,
      "expired": false,
      "scopes": [
        "*"
      ],
      "createdAt": "2025-01-15T10:30:00.000Z",
      "max_per_tx": null,
      "max_per_month": null,
      "spent_this_month": 0,
      "parent_token_id": null,
      "agent_identity": null
    },
    {
      "id": "cm5def456",
      "name": "CI/CD",
      "key": "domani_sk_b...vwxy",
      "lastUsed": null,
      "expiresAt": "2025-05-01T14:00:00.000Z",
      "expired": false,
      "scopes": [
        "domains:read",
        "domains:write"
      ],
      "createdAt": "2025-02-01T14:00:00.000Z"
    }
  ]
}

curl https://domani.run/api/tokens \
  -H "Authorization: Bearer domani_sk_xxx"

Créer un nouveau jeton API

Crée un nouveau jeton API. La clé complète est renvoyée uniquement dans cette réponse : stockez-la en toute sécurité. Vous pouvez créer plusieurs jetons pour séparer l'accès de différentes applications.

{
  "id": "cm5ghi789",
  "name": "CI/CD Pipeline",
  "key": "domani_sk_x1Y2z3A4b5C6d7E8f9G0hIjK",
  "expiresAt": "2025-03-20T10:30:00.000Z",
  "scopes": [
    "domains:read",
    "domains:write"
  ],
  "createdAt": "2025-02-18T10:30:00.000Z",
  "max_per_tx": 25,
  "max_per_month": 100,
  "mailbox_ids": [],
  "http_route_policy": null
}

curl -X POST https://domani.run/api/tokens \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Pipeline"}'

Révoquer un jeton API

Révoque définitivement un jeton API. Toutes les applications utilisant ce jeton perdront immédiatement l'accès. Cette action ne peut pas être annulée.

{
  "success": true
}

curl -X DELETE https://domani.run/api/tokens/cm5abc123 \
  -H "Authorization: Bearer domani_sk_xxx"

Répertorier les événements d'audit de sécurité

Renvoie la piste d’audit de sécurité du compte, la plus récente en premier : cycle de vie du jeton (création, révocation, tentatives d’escalade), refus liés au plafond de dépenses et à max_price, frais, demandes de paiement et suppressions de compte bloquées. Utilisez-la pour surveiller l’activité des jetons de vos agents.

{
  "events": [
    {
      "id": "evt1",
      "tokenId": "cm5abc123",
      "type": "purchase.charged",
      "targetType": "domain",
      "targetId": "mysite.com",
      "metadata": {
        "amountCents": 1450,
        "operation": "buy",
        "method": "card"
      },
      "createdAt": "2026-07-11T10:00:00.000Z"
    },
    {
      "id": "evt2",
      "tokenId": "cm5abc123",
      "type": "purchase.denied_cap",
      "targetType": "domain",
      "targetId": "expensive.ai",
      "metadata": {
        "amountCents": 8470
      },
      "createdAt": "2026-07-11T09:58:00.000Z"
    }
  ],
  "next_cursor": null,
  "hint": "Security-relevant events for this account."
}

curl "https://domani.run/api/audit?limit=50" \
  -H "Authorization: Bearer domani_sk_xxx"

Répertorier les webhooks

Répertoriez tous les points de terminaison de webhook configurés pour votre compte. Renvoie l'URL, les événements souscrits et l'état actif pour chaque webhook. Les secrets ne sont jamais restitués après la création. Un jeton confiné à des boîtes aux lettres ne voit que les webhooks confinés à ses propres boîtes aux lettres.

{
  "webhooks": [
    {
      "id": "cm5wh001",
      "url": "https://example.com/webhooks/domani",
      "events": [
        "domain.purchased",
        "dns.updated"
      ],
      "active": true,
      "created_at": "2026-02-25T10:00:00.000Z"
    }
  ],
  "hint": "1 webhook(s)."
}

curl https://domani.run/api/webhooks \
  -H "Authorization: Bearer domani_sk_xxx"

Créer un webhook

Enregistrez un nouveau point de terminaison de webhook HTTPS. Les valeurs facultatives d’autorisation ou de X-API-Key sont chiffrées au repos et incluses dans chaque distribution. Le secret de signature n'est renvoyé qu'une seule fois. Maximum 5 webhooks par compte. Un webhook créé par un jeton confiné à des boîtes aux lettres est confiné aux mêmes boîtes aux lettres : il ne reçoit aucun événement de courrier d'une autre boîte aux lettres.

{
  "id": "cm5wh001",
  "url": "https://example.com/webhooks/domani",
  "events": [
    "domain.purchased",
    "dns.updated"
  ],
  "secret": "whsec_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "active": true,
  "created_at": "2026-02-25T10:00:00.000Z",
  "hint": "Webhook created. Save the secret - it won't be shown again. Use it to verify incoming payloads with HMAC-SHA256."
}

curl -X POST https://domani.run/api/webhooks \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hook","events":["domain.purchased","dns.updated"],"headers":{"Authorization":"Bearer sender_key_xxx"}}'

Mettre à jour le webhook

Mettez à jour l'URL d'un webhook, les événements souscrits, le statut actif ou les en-têtes d'authentification chiffrés. Envoyez uniquement les champs que vous souhaitez modifier. Un jeton confiné à des boîtes aux lettres n'atteint que les webhooks confinés à ses propres boîtes aux lettres (404 sinon).

Supprimer le webhook

Supprimez un point de terminaison de webhook. Toutes les distributions en attente seront annulées. Cela ne peut pas être annulé. Un jeton confiné à des boîtes aux lettres n'atteint que les webhooks confinés à ses propres boîtes aux lettres (404 sinon).

Lister les diffusions de webhooks

Obtenez les tentatives de distribution récentes pour un webhook. Affiche le type d'événement, l'état HTTP, le nombre de tentatives et les erreurs éventuelles. Utile pour déboguer les distributions ayant échoué. Un jeton confiné à des boîtes aux lettres n'atteint que les webhooks confinés à ses propres boîtes aux lettres (404 sinon).

{
  "deliveries": [
    {
      "id": "cm5del001",
      "replay_of_id": null,
      "event_type": "domain.purchased",
      "status": "delivered",
      "http_status": 200,
      "attempts": 1,
      "last_error": null,
      "created_at": "2026-02-25T10:05:00.000Z"
    }
  ],
  "hint": "1 delivery(ies) for this webhook."
}

Rejouer une diffusion de webhook

Clonez et restituez immédiatement un événement webhook immuable. La charge utile de l'événement et l'ID de l'événement restent identiques ; la signature HMAC reçoit un nouvel horodatage. Une clé d'idempotence requise garantit que les tentatives de l'appelant ne seront jamais envoyées deux fois. Un jeton confiné à des boîtes aux lettres n'atteint que les webhooks confinés à ses propres boîtes aux lettres (404 sinon). Une exception à la charge utile identique : un sujet copié d'un courrier d'authentification est envoyé masqué, car l'URL du webhook peut avoir changé depuis le premier envoi.

Répertorier les types d'événements de webhook

Répertoriez tous les types d’événements webhook disponibles avec des descriptions. Aucune authentification requise.

{
  "events": [
    {
      "type": "domain.purchased",
      "description": "A new domain was successfully registered"
    },
    {
      "type": "dns.updated",
      "description": "DNS records were changed for a domain"
    },
    {
      "type": "transfer.completed",
      "description": "A domain transfer completed successfully"
    }
  ]
}

curl https://domani.run/api/webhooks/events

Liste des notifications

Listez vos notifications dans l’application avec une pagination par curseur. Inclut les événements de transaction, les mises à jour d’annonce et les alertes système. Nécessite la portée notifications:read. Une notification écrite avant que les sujets de courrier soient masqués à l'écriture se lit avec le sujet du courrier d'authentification masqué, dans body et data.subject, pour un jeton sans email:auth_secrets.

Obtenez le nombre de notifications non lues

Point de terminaison léger pour interroger le nombre de notifications non lues. Nécessite la portée notifications:read.

{
  "unread_count": 3
}

Marquer la notification comme lue

Marquer une seule notification comme lue. Nécessite la portée notifications:read.

Marquer toutes les notifications comme lues

Marquez toutes les notifications non lues comme lues. Nécessite la portée notifications:read.

Obtenir les préférences de notification

Renvoie les préférences de notification de l'utilisateur pour chaque catégorie et canal (in_app, email). Les préférences manquantes sont activées par défaut. Nécessite la portée notifications:read.

Mettre à jour les préférences de notification

Mettez à jour les préférences de notification pour des catégories et des canaux spécifiques. Nécessite la portée notifications:read.