Zur Dokumentation springen
API

Eine Regel erstellen

Bedingungen auf der einen Seite, Aktionen auf der anderen. Aktiv, sofern Sie nichts anderes sagen.

POSTapi.openemail.uk/rules

Führt den echten Aufruf gegen Ihren Workspace aus, mit Ihrem eigenen Schlüssel.

POST /rules

Bedingungen auf der einen Seite, Aktionen auf der anderen. Aktiv, sofern Sie nichts anderes sagen.

Beispiel

Benötigt rules:write. Liefert 201. position wird nicht akzeptiert. Eine neue Regel wird ans Ende der Liste gehängt, und verschoben wird sie mit 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  }'
Antwort
{  "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"}

Eine hier erstellte Regel ist AKTIV und greift ab der nächsten Nachricht. Das ist der richtige Standard für einen Aufruf, den jemand bewusst gemacht hat, und es ist das Gegenteil des MCP-Tools createRule, das dieselbe Regel DEAKTIVIERT schreibt, weil ein Modell, das entscheidet, Mail zu archivieren, nicht archivieren sollte, bevor ein Mensch die Regel nachgelesen hat.

Ein doppelter name auf derselben Connection ist rule_name_taken, ein 409. Über den Namen wird eine Regel im Ausführungsprotokoll und im Einstellungsbildschirm erkannt; zwei Regeln namens „Newsletters“ ergeben also einen Bericht, den niemand lesen kann.

Die 101. Regel ist rule_limit_reached, ein 422. Die Obergrenze ist ein Schutz gegen ein Skript in einer Schleife und keine Abrechnungsgrenze, und sie ist nicht gesperrt. Zwei gleichzeitige Erstellungen bei Stand 99 können beide durchgehen.

Was eine Bedingung fragen kann

Eine Bedingung ist { field, op, value }, mit einem optionalen header, der angibt, welcher Header gelesen wird, und einem optionalen negate. value ist auf der Leitung IMMER ein string. Numerische Felder werden nach Number(value) als Zahlen verglichen, und die beiden booleschen Felder nehmen die literalen Strings "true" und "false", weil ein Feld mit einem Typ ein Schema ist, das ein OpenAPI-Generator beschreiben kann, und eine Union aus dreien nicht.

FeldLiestOperatoren
`from`Der From:-Header, normalisiert so, wie die Blockliste ihn normalisiert.text
`from_domain`Die Domain von From: und deren ÜBERGEORDNETE Domains, bis hinunter auf zwei Labels: Eine Nachricht von mail.corp.example.com trifft auch auf corp.example.com und example.com zu und trifft bei com auf nichts.text
`envelope_from`Das SMTP-MAIL FROM. Auf jeder Mailingliste verschieden von from, und die einzige Identität, gegen die ein reject geschrieben werden darf.text
`to`, `cc`, `bcc`Eine beliebige Adresse in diesem Header.text
`recipient`Eine beliebige Adresse in to, cc oder bcc: die Kurzform für alle drei.text
`reply_to`Der Reply-To-Header.text
`delivered_to`Die kanonische Adresse, an die diese Kopie zugestellt wurde, ohne Plus-Tag und kleingeschrieben; so wird ein catch-all-Alias getroffen.text
`subject`Die Betreffzeile, wie sie eingegangen ist.text
`body`Der Textteil oder das auf Text reduzierte HTML. Gedeckelt, sodass ein 20 MB großer Body nicht vollständig durchsucht wird.text
`header`Ein beliebiger Header, benannt im header-Feld der Bedingung selbst. Dort erforderlich und vor dem Vergleich kleingeschrieben.text
`list_id`Der List-Id-Header: die Kennung, mit der sich eine Mailingliste ausweist.text
`attachment_name`Der Dateiname eines beliebigen Anhangs.text
`attachment_type`Der MIME-Typ eines beliebigen Anhangs, z. B. application/pdf.text
`has_attachment`Ob überhaupt einer vorhanden ist.equals "true" / "false"
`spam`Das Spam-Urteil, zu dem der Zustellpfad gekommen ist, bevor Ihre Regeln liefen.equals "true" / "false"
`attachment_size`Die Größe eines Anhangs in Bytes. Ein Vergleich trifft zu, wenn irgendein Anhang ihn erfüllt.gt, lt, equals
`message_size`Die gesamte Nachricht auf der Leitung, in Bytes.gt, lt, equals
`hour`Stunde des Eingangs, 0–23, UTC.gt, lt, equals
`weekday`Tag des Eingangs, 0–6, Sonntag ist 0, UTC.gt, lt, equals
OperatorWas er tut
`matches`Ein Glob, und nur ein Glob: * für eine beliebige Folge von Zeichen, ? für genau eines. Keine regulären Ausdrücke. Ein Muster von einem API-Client läuft auf dem Zustellpfad, und eines mit katastrophalem Backtracking bedeutet dort ein Postfach, das nichts mehr empfängt.
`contains`Teilzeichenkette, ohne Beachtung der Groß-/Kleinschreibung.
`equals`Der gesamte Wert, ohne Beachtung der Groß-/Kleinschreibung. Bei einem numerischen Feld numerische Gleichheit.
`starts_with`Präfix, ohne Beachtung der Groß-/Kleinschreibung.
`ends_with`Suffix, ohne Beachtung der Groß-/Kleinschreibung.
`gt`, `lt`Numerisch, nur auf den vier numerischen Feldern. Ein Textfeld mit gt trifft nie zu.

Ein matches-Muster muss mindestens zwei eigene alphanumerische Zeichen enthalten, dieselbe Hürde, die die Blockliste anlegt. Ein bloßes * wird beim Schreiben abgelehnt, statt angenommen zu werden und dann stillschweigend auf jede jemals eingehende Nachricht zuzutreffen; das wäre ein Ausfall und keine Regel.

Eine Bedingung, die die Engine nicht beantworten kann (ein unbekanntes Feld von einem neueren Client, ein Muster, das sich nicht kompilieren lässt, contains ""), gilt als Frage, die nie gestellt wurde, und nicht als falsch, und negate dreht sie nicht um. Diese Unterscheidung ist tragend: Eine negierte kaputte Bedingung, die als falsch gälte, würde ihre Regel bei jeder Nachricht im Postfach auslösen. equals "" wird beachtet, denn „die Betreffzeile ist leer“ ist eine echte Frage.

Was eine Regel tun kann

Aktion`value`Was passiert
`label`eine Label-IDFügt das Label hinzu. USER_…-IDs stammen aus GET /labels.
`remove_label`eine Label-IDEntfernt es. Dasselbe Label in beiden zu nennen wird aufgelöst, bevor die Nachricht abgelegt wird, statt der zuletzt ausgeführten Aktion überlassen zu werden.
`archive`keinerLegt sie außerhalb des Posteingangs ab.
`mark_read`keinerEntfernt UNREAD.
`star`keinerFügt STARRED hinzu.
`spam`keinerLegt sie unter Spam ab.
`trash`keinerLegt sie unter Trash ab und entfernt die Labels, die eine in den Papierkorb verschobene Nachricht nicht behält.
`forward`eine AdresseSendet eine Kopie weiter. Lesen Sie den Hinweis unten, bevor Sie das einsetzen.
`reply`eine Template-ID oder ein SlugAntwortet automatisch mit einem veröffentlichten Template, vorbehaltlich des Schleifenschutzes unten.
`block_sender`keinerNimmt den Absender in die Blockliste auf, sodass die nächste Nachricht schon an der Tür abgewiesen wird.
`reject`keinerWeist die Nachricht zur SMTP-Zeit mit 550 5.7.1 Message refused by the recipient ab. Nur Envelope. Siehe unten.

reject wird beim Schreiben abgelehnt, wenn dieselbe Regel nicht mindestens eine envelope_from-Bedingung trägt: reject_needs_envelope, ein 422. Ein 550 antwortet demjenigen, der uns die Nachricht übergeben hat, und auf einer Mailingliste ist das die LISTE, die die Abweisung als abprallenden Abonnenten liest und den Leser von etwas abmeldet, bei dem er nur wollte, dass eine einzelne Person aufhört zu posten. Selbst wenn die Bedingung geschrieben ist, wird ein Treffer, der nur aus den Header-Identitäten stammt, auf die Ablage unter Spam herabgestuft, weil der Envelope die einzige Identität ist, auf die eine Abweisung ehrlich zielen kann.

Ein regelgesteuertes forward geht über den Sendepfad hinaus, und der BAUT die Nachricht NEU auf: Die ursprüngliche DKIM-Signatur überlebt das nicht, ebenso wenig exotische Teile, ungewöhnliche Header oder alles jenseits der ausgehenden Größenobergrenze, die eine 25 MB große Nachricht mit Anhängen überschreitet. Es ist eine Kopie dessen, was eingegangen ist, und nicht die eingegangene Nachricht selbst. Die Adresse wird beim Schreiben der Regel geprüft, ein unverifiziertes Ziel ist also ein 422 auf den Aufruf und keine Regel, die stillschweigend jede zehnte Nachricht verwirft.

reply antwortet keiner Maschine. Es wird unterdrückt, wenn die Nachricht Auto-Submitted (mit einem anderen Wert als no), Precedence: bulk|list|junk, List-Id, List-Unsubscribe, X-Autoreply oder X-Autorespond trägt, wenn der Envelope-Absender leer ist (die Form, die jeder Bounce hat), und wenn die Header überhaupt nicht gelesen werden konnten. Darüber hinaus erhält ein Absender höchstens eine automatische Antwort pro 24 Stunden aus einem bestimmten Postfach. Zwei Postfächer mit Antwortregeln und ohne Schutz schreiben einander so lange, bis es jemand bemerkt.