Aller à la documentation
API

Créer une règle

Les conditions d'un côté, les actions de l'autre. Activée sauf indication contraire.

POSTapi.openemail.uk/rules

Exécute le véritable appel sur votre espace de travail, avec votre propre clé.

POST /rules

Les conditions d'un côté, les actions de l'autre. Activée sauf indication contraire.

Exemple

Requiert rules:write. Renvoie 201. position n'est pas accepté. Une nouvelle règle s'ajoute à la fin de la liste, et pour la déplacer il y a POST /rules/reorder.

curl
curl -X POST "$OE/rules" -H "$AUTH" -H "Content-Type: application/json" \  -d '{    "name": "Receipts to their own label",    "match": "all",    "conditions": [      { "field": "from_domain", "op": "matches", "value": "*.stripe.com" },      { "field": "subject", "op": "contains", "value": "receipt" }    ],    "actions": [      { "type": "label", "value": "USER_RECEIPTS" },      { "type": "archive" }    ],    "stopProcessing": true  }'
Réponse
{  "object": "rule",  "id": "rul_7f3a1c94e05d3862c1f0a44b",  "name": "Receipts to their own label",  "description": null,  "enabled": true,  "position": 3,  "match": "all",  "conditions": [    { "field": "from_domain", "op": "matches", "value": "*.stripe.com", "negate": false },    { "field": "subject", "op": "contains", "value": "receipt", "negate": false }  ],  "actions": [    { "type": "label", "value": "USER_RECEIPTS" },    { "type": "archive" }  ],  "stopProcessing": true,  "lastMatchedAt": null,  "matchCount": 0,  "createdAt": "2026-08-30T10:41:02.000Z",  "updatedAt": "2026-08-30T10:41:02.000Z"}

Une règle créée ici est ACTIVE et agit dès le message suivant. C'est la bonne valeur par défaut pour un appel fait délibérément, et c'est l'inverse de l'outil MCP createRule, qui écrit la même règle DÉSACTIVÉE, parce qu'un modèle qui décide d'archiver du courrier ne doit pas archiver avant qu'une personne ait relu la règle.

Un name en double sur la même connexion donne rule_name_taken, un 409. Les noms sont ce qui permet de reconnaître une règle dans un journal d'exécution et dans l'écran des réglages : deux règles appelées « Newsletters » donnent un rapport que personne ne peut lire.

La 101e règle donne rule_limit_reached, un 422. Le plafond est un garde-fou contre un script en boucle plutôt qu'une limite comptable, et il n'est pas verrouillé. Deux créations concurrentes à 99 peuvent toutes deux réussir.

Ce qu'une condition peut demander

Une condition est { field, op, value }, avec un header facultatif nommant l'en-tête à lire et un negate facultatif. value est TOUJOURS une string sur le réseau. Les champs numériques sont comparés comme des nombres après Number(value), et les deux champs booléens prennent les chaînes littérales "true" et "false", parce qu'un champ avec un seul type est un schéma qu'un générateur OpenAPI sait décrire, et qu'une union de trois ne l'est pas.

ChampLitOpérateurs
`from`L'en-tête From:, normalisé comme la liste de blocage le normalise.texte
`from_domain`Le domaine de From: et ses PARENTS, jusqu'à deux labels : un message venant de mail.corp.example.com correspond aussi à corp.example.com et à example.com, et ne correspond à rien pour com.texte
`envelope_from`Le MAIL FROM SMTP. Différent de from sur toutes les listes de diffusion, et la seule identité contre laquelle un reject peut être écrit.texte
`to`, `cc`, `bcc`N'importe quelle adresse de cet en-tête.texte
`recipient`N'importe quelle adresse dans to, cc ou bcc : le raccourci pour les trois.texte
`reply_to`L'en-tête Reply-To.texte
`delivered_to`L'adresse canonique à laquelle cette copie a été livrée, étiquette « plus » retirée et mise en minuscules, ce qui permet de faire correspondre un alias catch-all.texte
`subject`La ligne d'objet telle qu'elle est arrivée.texte
`body`La partie texte, ou le HTML réduit en texte. Plafonné, afin qu'un corps de 20 Mo ne soit pas analysé en entier.texte
`header`N'importe quel en-tête, nommé dans le champ header de la condition elle-même. Obligatoire à cet endroit et mis en minuscules avant comparaison.texte
`list_id`L'en-tête List-Id : l'identifiant par lequel une liste de diffusion se désigne.texte
`attachment_name`Le nom de fichier de n'importe quelle pièce jointe.texte
`attachment_type`Le type MIME de n'importe quelle pièce jointe, par ex. application/pdf.texte
`has_attachment`S'il y en a une, tout simplement.equals "true" / "false"
`spam`Le verdict de spam auquel est parvenu le chemin de livraison, avant l'exécution de vos règles.equals "true" / "false"
`attachment_size`La taille d'une pièce jointe en octets. Une comparaison correspond dès qu'une pièce jointe la satisfait.gt, lt, equals
`message_size`Le message entier tel qu'il circule sur le réseau, en octets.gt, lt, equals
`hour`Heure d'arrivée, 0–23, UTC.gt, lt, equals
`weekday`Jour d'arrivée, 0–6, dimanche vaut 0, UTC.gt, lt, equals
OpérateurCe qu'il fait
`matches`Un glob, et rien qu'un glob : * pour n'importe quelle suite de caractères, ? pour un seul. Pas d'expressions régulières. Un motif venu d'un client API s'exécute sur le chemin de livraison, et un motif à retour arrière catastrophique y devient une boîte aux lettres qui cesse de recevoir.
`contains`Sous-chaîne, insensible à la casse.
`equals`La valeur entière, insensible à la casse. Sur un champ numérique, égalité numérique.
`starts_with`Préfixe, insensible à la casse.
`ends_with`Suffixe, insensible à la casse.
`gt`, `lt`Numérique, sur les quatre champs numériques uniquement. Un champ texte avec gt ne correspond jamais.

Un motif matches doit porter au moins deux caractères alphanumériques qui lui soient propres, la même barre que celle appliquée par la liste de blocage. Un * seul est refusé à l'écriture plutôt qu'accepté puis appliqué en silence à tous les messages qui arriveront un jour, ce qui est une panne et non une règle.

Une condition à laquelle le moteur ne peut pas répondre (un champ inconnu venu d'un client plus récent, un motif qui ne compile pas, contains "") est traitée comme une question jamais posée plutôt que comme fausse, et negate ne l'inverse pas. Cette distinction est porteuse : une condition cassée et négationnée, traitée comme fausse, déclencherait sa règle sur chaque message de la boîte. equals "" est honoré, parce que « la ligne d'objet est vide » est une vraie question.

Ce qu'une règle peut faire

Action`value`Ce qui se passe
`label`un id de libelléAjoute le libellé. Les ids USER_… viennent de GET /labels.
`remove_label`un id de libelléLe retire. Nommer le même libellé dans les deux est résolu avant le classement du message plutôt que laissé à celle qui s'est exécutée en dernier.
`archive`aucuneLe classe hors de la boîte de réception.
`mark_read`aucuneRetire UNREAD.
`star`aucuneAjoute STARRED.
`spam`aucuneLe classe sous Spam.
`trash`aucuneLe classe sous Trash, en retirant les libellés qu'un message mis à la corbeille ne conserve pas.
`forward`une adresseEn envoie une copie. Lisez la note ci-dessous avant de l'utiliser.
`reply`un id ou un slug de modèleRépond automatiquement avec un modèle publié, sous réserve du garde-fou anti-boucle ci-dessous.
`block_sender`aucuneAjoute l'expéditeur à la liste de blocage, de sorte que le message suivant est refusé dès la porte.
`reject`aucuneRefuse le message au moment SMTP avec 550 5.7.1 Message refused by the recipient. Enveloppe uniquement. Voir ci-dessous.

reject est refusé à l'écriture si la règle ne porte pas au moins une condition envelope_from : reject_needs_envelope, un 422. Un 550 répond à celui qui nous a remis le message, et sur une liste de diffusion c'est la LISTE, qui lit le refus comme un abonné en échec et désabonne le lecteur de quelque chose dont il voulait seulement qu'une personne cesse d'y publier. Même la condition écrite, une correspondance issue uniquement des identités d'en-tête est rétrogradée en classement dans Spam, parce que l'enveloppe est la seule identité que l'on puisse honnêtement viser par un refus.

Un forward piloté par une règle passe par le chemin d'envoi, qui RECONSTRUIT le message : la signature DKIM d'origine n'y survit pas, pas plus que les parties exotiques, les en-têtes inhabituels ou tout ce qui dépasse le plafond de taille sortant, qu'un message de 25 Mo avec pièces jointes franchira. C'est une copie de ce qui est arrivé, pas le message qui est arrivé. L'adresse est vérifiée au moment où la règle est écrite : une destination non vérifiée donne donc un 422 sur l'appel plutôt qu'une règle qui perd en silence un message sur dix.

reply ne répondra pas à une machine. Elle est supprimée lorsque le message porte Auto-Submitted (autre que no), Precedence: bulk|list|junk, List-Id, List-Unsubscribe, X-Autoreply ou X-Autorespond, lorsque l'expéditeur d'enveloppe est vide (la forme que prend tout rebond) et lorsque les en-têtes n'ont pas pu être lus du tout. En plus de cela, un expéditeur reçoit au plus une réponse automatique par 24 heures depuis une boîte donnée. Deux boîtes dotées de règles de réponse et sans garde-fou s'écrivent l'une à l'autre jusqu'à ce que quelqu'un s'en aperçoive.