# Référence de l’API HTTP ## Langues et codes d'erreur L'anglais est la langue par défaut. L'API, la console Web et les moteurs de rendu de notifications partagent les catalogues intégrés dans `internal/i18n/locales/` . `internal/i18n/languages.json` définit ces codes canoniques et noms natifs : | Code | Langue | | --------- | ------------------ | | `en` | English | | `zh-CN` | 简体中文 | | `zh-Hant` | 繁體中文 | | `ja` | 日本語 | | `ko` | 한국어 | | `de` | Deutsch | | `fr` | Français | | `es` | Español | | `pt-BR` | Português (Brasil) | - Lors de la première visite, la console utilise le `Accept-Language` du navigateur. Son sélecteur stocke localement le code canonique choisi. Le changement de langue de la console laisse les paramètres de notification enregistrés inchangés. - Les requêtes API, y compris les requêtes de gestion d'applications, négocient `Accept-Language` par pondérations de qualité. Les réponses incluent `Content-Language` et `Vary: Accept-Language` . Les préférences non prises en charge sont ignorées ; Les préférences manquantes, invalides ou totalement non prises en charge reviennent à `en` . Une langue de poids 0 est exclue de la négociation. - Les variantes régionales correspondent à leur langue prise en charge : `fr-CA` → `fr` , `es-MX` → `es` , `pt` / `pt-PT` → `pt-BR` . L'écriture chinoise est respectée : `zh-Hans` / `zh-CN` / `zh-SG` → `zh-CN` ; `zh-Hant` / `zh-TW` / `zh-HK` / `zh-MO` → `zh-Hant` . Un script explicite a priorité sur la région ; le simple `zh` utilise le chinois simplifié. - `GET /locales/default.json` sert le catalogue négocié ; `GET /locales/{canonical-code}.json` sert explicitement ce catalogue. Les chemins de catalogue inconnus renvoient `locale_not_supported` . - Paramètres de livraison `language` contrôle les notifications générées par l'avant-poste indépendamment de la langue de la demande ou de la console. Il accepte les codes canoniques et les variantes régionales prises en charge, conserve le code canonique et prend par défaut la valeur `en` lorsqu'il est omis ou vide. Une valeur explicite non prise en charge renvoie 400 `config_language_invalid` . - Le service de transmission des notifications génère un texte de notification de test natif en utilisant la langue de l'appareil couplé. La langue de notification de l'avant-poste ne remplace pas cette langue. Le service de transmission des notifications et l'application prennent chacun en charge leur propre ensemble de langues. - Les rôles de dossier standard et les noms de dossiers courants sont localisés dans la console. Les chemins IMAP bruts, les noms personnalisés et `folder_roles` restent inchangés dans les API ; Les applications localisent ces rôles avec leurs propres catalogues. Les titres des notifications continuent d'utiliser le nom du dossier feuille d'origine. Les noms saisis par l'utilisateur, les objets des e-mails, le contenu des e-mails et les codes de vérification restent littéraux. - Les journaux et la sortie CLI utilisent l’anglais. Les erreurs commerciales conservent les codes `snake_case` anglais stables et les paramètres nommés ; le stockage conserve les codes et les paramètres, et les couches d'affichage traduisent les messages. Les dates et les chiffres dans les réponses API conservent leurs formats lisibles par machine existants ; la console formate les horodatages en utilisant les paramètres régionaux choisis. ```json { "error": { "code": "unauthorized", "message": "Sign in with a valid session or API token." } } ``` `last_error` dans les enregistrements d’envoi et `notice` dans l’état des dossiers utilisent la même structure `{code, message, params?}`, par exemple `bark_http_error` avec `{"status":"503"}`. Utilisez `code` pour la logique et affichez `message`. Chaque boîte aux lettres réserve une connexion pour sa découverte de dossier et ses tests de connexion. La demande de l'observateur est `realtime Folder count + (1 if any scheduled Folders exist, otherwise 0)` , au maximum des connexions `connection_limit - 1` (9 par défaut) ; toutes les opérations pour cette boîte aux lettres restent ensemble dans `connection_limit` (2–100). Configurations enregistrées avec une limite de 1 démarrage en mode de récupération avec `configuration_invalid` . ## API HTTP `GET /` sert la page actuelle ; les actifs statiques et `/healthz` sont publics. Avant la configuration, tous les autres points de terminaison de gestion renvoient 403 `setup_required` . `POST /api/v1/setup` est disponible une fois ; `POST /api/v1/session` est public après la configuration. Toutes les API restantes nécessitent le cookie de session ou `Authorization: Bearer mwk_…` . Les sessions de cookies utilisent HttpOnly, SameSite=Strict, Path=/, Secure sur une connexion TLS ou HTTPS Origin, un délai d'inactivité de sept jours et un délai d'attente absolu de 30 jours. Chaque mutation authentifiée par cookie nécessite `X-CSRF-Token` et un HTTP(S) `Origin` dont l'hôte et le port facultatif correspondent exactement à l'hôte de la demande. Les demandes du porteur ignorent les contrôles CSRF. Un en-tête d'autorisation non valide échoue même lorsqu'un cookie valide est présent. Les échecs de connexion et de code de configuration partagent un budget d'adresse source : dix échecs toutes les 15 minutes, suivis de 429 `too_many_attempts` avec `Retry-After` en secondes. La source est Gin ClientIP utilisant les plages de proxy de confiance ci-dessus. Les changements de mot de passe utilisent également ce budget. Les origines intersites explicites sont rejetées lors de la connexion et de la configuration. Étant donné que chaque homologue du réseau privé est considéré comme un proxy, un client de votre réseau local peut définir X-Forwarded-For et répartir ses tentatives sur de nombreuses adresses sources. N'exposez pas l'écouteur d'avant-poste à un réseau local non fiable ; publiez-le uniquement via votre proxy inverse. Tous les corps JSON sont limités à 64 Ko ; les champs inconnus ou le JSON de fin renvoient 400. Les mots de passe comportent au minimum 12 caractères et 1 024 octets UTF-8 au maximum. Les noms d'utilisateur et les noms de jetons comportent entre 1 et 128 octets. Tous les horodatages de l'API de gestion sont des chaînes RFC 3339 au format UTC, y compris la livraison `created_at` / `accepted_at` , le jeton `created_at` / `last_used_at` , les vérifications de dossiers, les heures de journalisation et l'heure de génération des diagnostics. Les secondes fractionnaires préservent la précision stockée. Le jeton inutilisé `last_used_at` est nul ; les livraisons sans acceptation omettent `accepted_at`. Les décomptes, les durées et les révisions restent des chiffres. 401 identifie une session ou un jeton API non valide, ou des informations d'identification rejetées sur `POST /api/v1/session` . Un code de configuration incorrect renvoie 400 `setup_code_invalid` ; l'assistant revient à l'étape de code et conserve le nom d'utilisateur. Un mot de passe actuel incorrect sur `PUT /api/v1/admin/password` renvoie 400 `current_password_invalid` et compte dans la limite d'échec ; la session en cours reste valable. Les échecs de connexion et les erreurs de mot de passe actuel apparaissent dans le formulaire, préservant ainsi ses entrées. | Méthode | Chemin | Demande / réponse | | ------------------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | POST | `/api/v1/setup` | `{ "code":"XXXX-XXXX-XXXX", "username":"admin", "password":"…" }` ; 201, cookie + `{ "csrf_token":"…" }` ; répéter la configuration : 409 | | POST | `/api/v1/session` | `{ "username":"admin", "password":"…" }` ; 200, cookie + jeton CSRF | | GET | `/api/v1/session` | `{ "authenticated":true, "csrf_token":"…" }` ; Le porteur renvoie `method: "token"` au lieu de CSRF | | DELETE | `/api/v1/session` | 204 ; révoque la session de cookie en cours ; nécessite une séance | | PUT | `/api/v1/admin/password` | `{ "current_password":"…", "password":"…" }` ; 204, révoque les autres sessions ; Le porteur révoque toutes les sessions | | POST | `/api/v1/tokens` | `{ "name":"automation" }` ; 201, `{ "id":"…", "name":"…", "created_at":"2026-09-29T01:02:03Z", "last_used_at":null, "token":"mwk_…" }` | | GET | `/api/v1/tokens` | `{ "tokens":[…] }` ; métadonnées uniquement | | DELETE | `/api/v1/tokens/:id` | 204 ; révoque un jeton ; la suppression répétée renvoie également 204 | | GET | `/api/v1/mailboxes` | `{ "mailboxes":[…] }` ; vues de boîtes aux lettres expurgées | | POST | `/api/v1/mailboxes` | Créez avec le formulaire de boîte aux lettres ci-dessous ; 201, vue expurgée avec `id` généré et révision 1 | | GET / PUT / DELETE | `/api/v1/mailboxes/:id` | Lire/mettre à jour avec la révision actuelle/supprimer (204) ; L'ID manquant renvoie 404 `mailbox_not_found` | | POST | `/api/v1/mailboxes/test` | Testez un formulaire non enregistré ; renvoie `{ "folders":[…] }` , conserve la configuration inchangée | | POST | `/api/v1/mailboxes/:id/test` | Testez le formulaire avec les informations d'identification omises et fusionnées à partir de cette boîte aux lettres | | GET | `/api/v1/mailboxes/:id/folders` | Découvrez les dossiers sélectionnables en utilisant le budget de cette boîte aux lettres | | GET / PUT | `/api/v1/mailboxes/:id/subscriptions` | Lire/enregistrer les abonnements en utilisant leur propre révision ; la sauvegarde réussie renvoie 202 | | GET / PUT | `/api/v1/settings/delivery` | Lire/enregistrer les paramètres de livraison globaux avec leur propre révision | | DELETE | `/api/v1/settings/delivery` | Effacez le canal et les informations d'identification enregistrés avec `{revision}` ; 204, révision périmée 409 | | POST | `/api/v1/settings/delivery/test` | Testez le formulaire de livraison avec les identifiants enregistrés fusionnés ; 204, configuration inchangée | | GET | `/api/v1/status` | États des dossiers, canal, nombre de livraisons et notifications ciblées | | GET | `/api/v1/diagnostics` | Télécharger un rapport JSON rédigé sans journaux d'exécution | | GET | `/api/v1/logs` | Journaux opérationnels authentifiés ; Filtres `after` , `level` , `mailbox_id` , `limit` (voir ci-dessous) | | GET | `/api/v1/deliveries` | 50 derniers enregistrements de livraison, y compris le sujet et le résumé de la boîte aux lettres/dossier | | POST | `/api/v1/test-push` | Envoyez un test en utilisant les paramètres enregistrés ; 204 une fois accepté, configuration inchangée | | POST | `/api/v1/deliveries/:id/retry` | Remettre en file d'attente une tâche `dead` ; 202 | Les enregistrements de livraison incluent un objet `message` facultatif : `mailbox_id` , `mailbox_label` , `folder` , `subject` (chaîne ou null) et `test` (booléen). Les noms sont des instantanés du temps de mise en file d’attente et survivent au renommage ou à la suppression de la boîte aux lettres. Un sujet nul signifie qu'il n'a pas été retenu ; une chaîne vide signifie que le mail n'a pas de sujet. Les notifications de test contiennent `test=true` et aucune source de boîte aux lettres. L'API omet l'expéditeur et le corps de ce résumé. Exemple de création de boîte aux lettres : ```json { "label": "Work mailbox", "host": "imap.example.org", "port": 993, "username": "user@example.org", "password": "…", "connection_limit": 10 } ``` L'avant-poste autorise au maximum 20 boîtes aux lettres enregistrées, y compris les configurations invalides en attente de réparation ; la création suivante renvoie 400 `mailbox_limit_exceeded` . Les identifiants sont générés sous la forme `mbx_` plus une chaîne aléatoire et restent stables. `label` utilise par défaut le nom d'utilisateur (adresse e-mail), autorise au maximum 64 caractères Unicode et rejette les sauts de ligne. Un nom d'utilisateur de plus de 64 caractères nécessite une étiquette explicite plus courte. Les étiquettes omises lors de la mise à jour conservent la valeur enregistrée ; une étiquette vide utilise le nom d'utilisateur soumis. La boîte aux lettres PUT utilise le même formulaire plus `"revision":1` (la valeur lue dans GET ) et nécessite un hôte, un port et un nom d'utilisateur. Si l’hôte, le port et le nom d’utilisateur restent identiques, le mot de passe omis conserve la valeur enregistrée ; un mot de passe vide et explicite est rejeté. Le `connection_limit` omis conserve la valeur actuelle ; les nouvelles boîtes aux lettres sont par défaut 10, plage 2 à 100. La création de POST omet la révision ou envoie 0. Les routes de test acceptent les mêmes champs sans nécessiter de révision et conservent la configuration inchangée. Le test non enregistré nécessite des informations d'identification ; le test de boîte aux lettres enregistrée fusionne les informations d'identification omises uniquement à partir de l'ID spécifié. Une vue GET de boîte aux lettres comprend `id` , `label` , `revision` , `host` , `port` , `username` , `connection_limit` , `connections_in_use` et `"password":{"configured":true}` . Une boîte aux lettres invalide récupérée signale `configured:false` et conserve son ID et sa révision afin de pouvoir être réparée. L'objet mot de passe GET est une vue et non une valeur d'écriture valide. Chaque boîte mail dispose d'un budget de connexion indépendant. Les dossiers en temps réel consomment chacun un emplacement ; tous ses dossiers planifiés en consomment un. Leur demande combinée doit correspondre à `connection_limit - 1` , en réservant un emplacement pour la gestion. L'abonnement PUT et les modifications de limite de boîte aux lettres appliquent cette formule ; la capacité épuisée renvoie `connection_budget_exceeded` . Le test d'une boîte aux lettres non enregistrée utilise un budget temporaire. Les points de terminaison de test non enregistré, de test de boîte aux lettres enregistrée et de découverte de dossier partagent en outre une limite de concurrence globale de 2 ; les demandes excédentaires renvoient immédiatement 429 `discovery_busy`. L'achèvement ou l'annulation libère l'admission. Exemple de livraison PUT pour une voie initialement non configurée : ```json { "revision": 0, "channel": "bark", "preview": "off", "retry_count": 0, "language": "en", "bark": { "endpoint": "https://api.day.app", "key": "…" } } ``` Lisez `/settings/delivery` avant chaque mise à jour et envoyez sa révision ; la première sauvegarde avance de 0 à 1. Pushover utilise `"pushover":{"token":"…","user":"…"}` ; Le webhook utilise `"webhook":{"url":"https://hooks.example.org/mail","secret":"…"}` . La chaîne, l'aperçu et la révision sont requis. La langue omise et le nombre de tentatives utilisent les valeurs par défaut. Si la destination reste identique, les identifiants omis, y compris l’URL Webhook, conservent les valeurs enregistrées ; un identifiant actif vide explicite est rejeté. GET remplace chaque identifiant par `{"configured":true|false}` . Le point final de test distinct ne nécessite pas de révision. Les créations de boîtes aux lettres et les modifications de connexion testent la connexion/connexion avant d'enregistrer. Si l'hôte, le port, le nom d'utilisateur et la limite de connexion correspondent aux valeurs enregistrées et que le mot de passe est omis, PUT modifie uniquement l'étiquette : la vérification des révisions et la persistance s'appliquent toujours, tandis que les tests et le remplacement de l'observateur sont ignorés. Les tâches en file d'attente conservent leur étiquette d'origine ; les tâches futures utilisent la nouvelle étiquette. La création ou la mise à jour d'une identité déjà utilisée par une autre boîte aux lettres renvoie 409 `mailbox_duplicate` (l'hôte et le nom d'utilisateur ne respectent pas la casse, le port est exact) ; la création simultanée ne peut enregistrer cette identité qu'une seule fois. Livraison PUT enregistre tous les canaux après le champ, l'adresse, l'état d'appairage sélectionné et la validation de la révision, sans envoyer de test ni contacter un fournisseur. Les tests de livraison explicites laissent les paramètres enregistrés inchangés ; leur échec ne bloque pas une sauvegarde ultérieure. Les tests de boîte aux lettres s'exécutent en dehors des verrous de configuration et maintiennent les observateurs existants actifs ; un test de boîte aux lettres ayant échoué conserve sa configuration précédente. Les révisions des paramètres obsolètes renvoient 409 `settings_conflict` ; une modification d’abonnement lors d’un test de boîte aux lettres invalide également l’instantané de ce test. Rechargez avant de réessayer. Chaque boîte aux lettres et les paramètres de remise globaux ont des révisions indépendantes, de sorte que les modifications apportées à différentes boîtes aux lettres ou à une boîte aux lettres et la livraison n'entrent pas en conflit. Un PUT réussi renvoie la vue expurgée et s'applique immédiatement. Un changement de connexion à la boîte aux lettres arrête ses propres observateurs avant la sauvegarde et la réinitialisation facultative du curseur ; une sauvegarde ratée les restaure. Les autres boîtes aux lettres continuent de fonctionner. Les modifications de livraison préservent l’instantané d’une tentative en vol ; les tentatives ultérieures utilisent le nouveau. Les tâches en attente attendent pendant que la livraison n'est pas configurée. `GET /api/v1/mailboxes/:id/subscriptions` renvoie `{"revision":1,"folders":[{"name":"INBOX","check":"realtime"},{"name":"Clients","check":"5m"}]}` . PUT envoie la révision lue et le tableau `folders` complet ; un tableau vide se désabonne de tout. Les noms sont uniques dans chaque boîte aux lettres, INBOX est normalisé et chaque nom fait au maximum 4 096 octets UTF-8. Chaque dossier nécessite `name` et `check` ; le chèque est `realtime`, `5m` ou `15m`. Les vérifications manquantes/invalides et le format de tableau de chaînes précédent renvoient 400. La formule de demande de connexion ci-dessus remplace la limite du nombre de dossiers. La modification de la seule vérification préserve la progression, rattrape les nouveaux messages et conserve les ID d'événement existants ; l'annulation et la réinscription ultérieure créent une nouvelle base de référence. Tous les champs sont obligatoires. L'enregistrement renvoie 202 avec la prochaine révision ; les révisions obsolètes renvoient 409 `subscriptions_conflict` . L'existence du dossier est confirmée par l'observateur, de sorte que les abonnements peuvent être supprimés lorsque la boîte aux lettres est hors ligne. Les échecs de stockage renvoient 503 et préservent les abonnements en cours. Chaque article `/status.folders[]` comprend `mailbox_id`, `mailbox_label` et `check`. `mode` est `idle` , `poll` ou `scheduled` ; Les dossiers planifiés incluent également `next_check` (heure RFC 3339, y compris les délais de nouvelle tentative). Les dossiers en temps réel omettent `next_check` . La configuration enregistrée qui échoue JSON ou la validation du modèle n'est plus configurée, avec `configuration_invalid` dans `/status.notices` sous `mailbox:` ou `delivery` ; PUT répare cet article. Les abonnements excédentaires suspendent uniquement cette boîte aux lettres et signalent `connection_budget_exceeded` sous `subscriptions:` . Réduire les abonnements ou augmenter sa limite reprend la surveillance. Les échecs de déchiffrement arrêtent le démarrage. La liste d'autorisation de diagnostic contient l'heure de génération, les informations de build/Go/plateforme, le nombre de files d'attente et les états de boîte aux lettres anonymes et d'observateur, notamment `check` et `mode` . `mailboxes[].index` et `watches[].mailbox_index` identifient « Boîte aux lettres 1 », « Boîte aux lettres 2 », etc. dans ce rapport ; les observateurs de chaque boîte aux lettres ont leur propre `index`. Les entrées de boîte aux lettres incluent les codes de notification de configuration/abonnement. Seul `imap_folder_rejected` peut inclure `watches[].response_code` . Le rapport omet les ID de boîte aux lettres, les noms d'affichage, les adresses, les noms de serveur, les noms de dossiers, les données de message, les ID de tâche, les informations d'identification et tous les autres paramètres d'erreur. États de la tâche : `pending` attend une demande, `accepted` signifie que le canal a accepté la demande, `dead` signifie que la tentative s'est terminée par un échec enregistré. ## Journaux d'exécution Utilisez `docker compose logs -f core` (ou `docker logs ` ) pour la sortie JSON stderr. Les clients authentifiés peuvent interroger les mêmes événements opérationnels via `GET /api/v1/logs?after=0&level=info&mailbox_id=mbx_example&limit=200`. Un cookie de session ou un jeton API est requis. L'anneau en mémoire conserve les **2000** entrées d'information/avertissement/erreur les plus récentes et s'efface au redémarrage. `after` est une séquence non négative exclusive ; `level` sélectionne ce niveau et au-dessus (par défaut `info`) ; Le `mailbox_id` omis inclut toutes les boîtes aux lettres et opérations globales. La valeur par défaut de `limit` est 200, plage 1 à 500. Les paramètres non valides renvoient 400 `logs_request_invalid` . ```json { "entries": [ { "seq": 42, "time": "2026-09-29T00:00:00Z", "level": "info", "message": "Folder connection established", "attrs": { "mailbox_id": "mbx_example", "folder": "INBOX", "mode": "idle", "check": "realtime" } } ], "next": 42, "cleared_through": 0 } ``` Utilisez `next` comme `after` de la prochaine demande. À la limite de la page, c'est la dernière séquence renvoyée ; après avoir analysé l'instantané, il avance jusqu'à la fin de l'instantané, y compris lorsque les filtres ne correspondent à rien. Les entrées expulsées sont ignorées. Si le redémarrage renvoie `next < after` , réinitialisez le curseur à 0. Les entrées sont classées par séquence. Les journaux couvrent les cycles de vie des boîtes aux lettres et des dossiers, le nombre de références/mises en file d'attente, les tentatives de livraison, les modifications de configuration et les actions de l'administrateur. Les événements globaux utilisent un `mailbox_id` vide. Seuls ces attributs scalaires sont exposés : `mailbox_id` , `folder` , `mode` , `check` , `code` , `event_id` , `channel` , `attempt` , `duration_ms` , `http_status` , `next_attempt` , `backoff_seconds` , `count` , `revision` , `token_id` , `version` , `listen` . `http_status=0` signifie qu'aucune réponse HTTP n'a été reçue ; `token_id` est un identifiant d'enregistrement public, et non la valeur du jeton. Les mots de passe, les valeurs de jeton/session, les codes de configuration, l'expéditeur, le sujet, les corps et les URL d'identification sont omis. La ligne de code de configuration va uniquement à la console. Les journaux contiennent des noms de dossiers ; l'exportation de diagnostic anonyme exclut les journaux et les noms. Les tests de découverte de dossiers et de boîte aux lettres d'administrateur renvoient `folders` comme tableau de chemin d'origine plus `folder_roles` en option, une carte du chemin vers `inbox`, `drafts`, `sent`, `trash`, `junk`, `archive`, `all` ou `flagged` . Les rôles proviennent des attributs IMAP SPECIAL-USE ; INBOX est reconnu par son nom défini par le protocole. L'interface utilisateur Web utilise des correspondances exactes, insensibles à la casse, pour les noms de dossiers anglais courants lorsque les rôles sont absents. Les noms traduits affichent le chemin d'origine entre parenthèses ; les autres noms restent inchangés. Afficher les traductions ne modifie jamais les chemins d’abonnement. Les titres des notifications utilisent le segment final des chemins de dossiers séparés par des barres obliques ; les champs du dossier structuré conservent le chemin complet. Les tests de boîte aux lettres d'application continuent de renvoyer uniquement l'état de connexion. `GET /api/v1/session` inclut `username` pour une session de cookie authentifiée. L'authentification par jeton conserve sa réponse existante. ### Appareil de réception d'applications Les paramètres de livraison incluent `native_pairing_id` . Pour le canal `native`, sélectionnez un appairage actif parmi `/api/v1/native/devices` . Les notifications de test et les nouveaux événements ciblent uniquement ce appairage. L'omission du champ lors d'une mise à jour préserve la sélection enregistrée ; une sélection vide renvoie `native_target_required` . Une sélection indisponible renvoie `native_target_unavailable` . La révocation de l’appairage natif sélectionné efface atomiquement le canal et native_pairing_id et incrémente la révision une fois. Les autres cibles et canaux restent intacts. Les livraisons existantes conservent leur cible et leur résultat de révocation. Voir [synchronisation de l’appairage](https://github.com/mingzaily/mailwake/blob/main/docs/native-push.md#pairing-revocation-synchronization) pour connaître le comportement de synchronisation, de concurrence et de redémarrage. L'autorisation des applications gère l'administration et l'autorisation push de manière indépendante. La révocation de l’une ou l’autre autorisation laisse l’autre inchangée. ### Notifications de tests natifs L'avant-poste utilise `POST /v1/pairing-tests` signé avec `{pairing_id,test_id}` (un nouvel UUID par test explicite). Le service de transmission des notifications génère du contenu fixe et le soumet de manière synchrone à APNs sans nécessiter le droit Native Push. Les tests de formulaire, les tests de paramètres enregistrés dans l'application et `/api/v1/test-push` utilisent ce même chemin. Les tests sont distincts de la boîte d'envoi du courrier et ne comportent aucune tentative de livraison automatique. L'avant-poste renvoie HTTP 204 uniquement lorsque le service de transmission des notifications signale `accepted` . Rejet de APNs, résultats inconnus et `sending` renvoient une erreur localisée ; la limitation du débit du service de transmission des notifications fait que l'avant-poste renvoie HTTP 429 avec `Retry-After` . Les journaux sécurisés incluent l'état HTTP du service de transmission des notifications et le code d'erreur stable, à l'exclusion des corps de réponse, des jetons et du contenu des notifications. L’avant-poste et l’application partagent les quotas quotidiens par minute et par sujet existants du service de transmission des notifications ainsi que l’idempotence `(device_id,test_id)`. Un utilisateur démarrant un autre test crée un nouvel ID de test. Le courrier formel utilise `/v1/push` et reste limité aux droits, quels que soient l'ID d'événement ou les indicateurs de test client. Déployer l'itinéraire de test de appairage du service de transmission des notifications avant cette version d'avant-poste ; l'avant-poste ne recourt pas à la livraison du courrier payante. ## Effacer l'historique de livraison et les journaux d'exécution - `DELETE /api/v1/deliveries` renvoie `200 {"deleted":N}` . Il supprime définitivement les enregistrements terminés ( `accepted` / `dead` ) dans l'historique complet, y compris leurs enregistrements natifs associés. Les livraisons/tentatives en attente, les enregistrements natifs toujours en attente/en file d'attente/envoi ou planifiés pour des contrôles de statut et les mises à jour d'activité native en attente sont conservés. La suppression des échecs supprime leur option de nouvelle tentative manuelle. Les points de contrôle et la configuration de la boîte aux lettres sont conservés. - `DELETE /api/v1/logs` renvoie `200 {"cleared_through":N}` et efface l'anneau en mémoire partagé pour tous les niveaux et boîtes aux lettres. Les numéros de séquence continuent d'augmenter ; Les journaux stderr/container et les fichiers exportés restent. `GET /api/v1/logs` renvoie également `cleared_through` ; les clients suppriment les entrées mises en cache avec `seq <= cleared_through` avant d'ajouter les entrées renvoyées. - Les deux points de terminaison nécessitent une session d'administrateur + Origin/CSRF ou un jeton d'API d'administrateur. Les informations d’identification de l’appareil d’application n’accordent pas ces opérations. Un nettoyage répété est sûr ; de nouveaux travaux et entrées de journal peuvent apparaître après l'opération. ## Contenu des messages de l’application `POST /api/v1/app/content` utilise un identifiant de contrôleur lié à l’appareil et l’autorisation `content` accordée par le propriétaire. Envoyez `{ "reference": }` ; la réponse contient `text`, `truncated`, éventuellement un `html` assaini et `has_remote_images`. La lecture est gratuite. Une fois le corps lisible, `POST /api/v1/app/content/read`, avec les mêmes identifiants, autorisation et référence, marque le message comme lu dans la boîte mail. Le succès renvoie `204 No Content` et `Cache-Control: no-store`. La seule récupération du contenu conserve l’état de lecture. Les deux opérations vérifient l’autorisation actuelle, le dossier suivi, l’identité de la boîte mail et la référence du message. ## Destination des identifiants Lors des tests et de l’enregistrement, modifier `host`, `port` ou `username` exige de saisir à nouveau le mot de passe enregistré ; sinon, la réponse est 400 `mailbox_password_required_for_change`. Modifier l’adresse Bark enregistrée exige la clé de l’appareil, même si un autre canal est sélectionné ; sinon, la réponse est 400 `bark_key_required_for_change`. Le port, le chemin et la barre finale font partie de l’adresse. Une requête rejetée n’ouvre aucune connexion et conserve la configuration et la révision. ## Diagnostic des requêtes App Les exports utilisent `schema_version: 2`. `app_requests` contient au maximum 300 requêtes App récentes et terminées, issues du journal partagé de 2000 événements en mémoire : heure, `request_id` généré par le serveur (également dans `X-Request-ID`), modèle de route, méthode, statut HTTP, durée, étape, résultat et codes sûrs. Les identifiants de ressources, paramètres de requête, secrets, références signées, corps des messages et journaux complets sont exclus. Un redémarrage ou un effacement des journaux supprime ces entrées ; les autres événements peuvent évincer les plus anciennes. Le téléchargement actualise le rapport. Les requêtes qui ne parviennent pas au serveur nécessitent les diagnostics App. `POST /api/v1/app/content/read` vérifie UID et indicateurs. Un message déjà lu réussit ; un message non lu est marqué puis vérifié à nouveau. STORE OK seul ne prouve pas son existence. UID absent, UIDVALIDITY modifié ou dossier explicitement absent donnent 404 ; refus du fournisseur ou de permission, 503 ; délai dépassé, 504. Le corps en cache reste lisible si la référence distante expire.