Utwórz regułę
Warunki po jednej stronie, akcje po drugiej. Włączona, chyba że powiesz inaczej.
Uruchamia prawdziwe wywołanie na twojej przestrzeni roboczej, twoim własnym kluczem.
POST /rules
Warunki po jednej stronie, akcje po drugiej. Włączona, chyba że powiesz inaczej.
Przykład
Wymaga rules:write. Zwraca 201. position nie jest przyjmowane. Nowa reguła dopisuje się na koniec listy, a przesuwa ją POST /rules/reorder.
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 }'{ "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"}Reguła utworzona tutaj jest WŁĄCZONA i zaczyna działać na następnej wiadomości. To właściwa wartość domyślna dla wywołania wykonanego świadomie i odwrotność narzędzia MCP createRule, które zapisuje tę samą regułę WYŁĄCZONĄ, bo model, który postanawia archiwizować pocztę, nie powinien jej archiwizować, zanim człowiek nie przeczyta reguły.
Powtórzona name na tym samym połączeniu to rule_name_taken, 409. Po nazwach rozpoznaje się regułę w dzienniku uruchomień i na ekranie ustawień, więc dwie reguły o nazwie „Newsletters” to raport, którego nikt nie przeczyta.
Sto pierwsza reguła to rule_limit_reached, 422. Ten limit to zabezpieczenie przed skryptem w pętli, a nie granica rozliczeniowa, i nie jest blokowany. Dwa jednoczesne utworzenia przy 99 mogą oba się powieść.
O co może zapytać warunek
Warunek to { field, op, value }, z opcjonalnym header wskazującym, który nagłówek odczytać, i opcjonalnym negate. value jest ZAWSZE stringiem na łączu. Pola liczbowe są porównywane jako liczby po Number(value), a dwa pola boolowskie przyjmują dosłowne stringi "true" i "false", bo jedno pole z jednym typem to schemat, który generator OpenAPI potrafi opisać, a unia trzech typów już nie.
| Pole | Co odczytuje | Operatory |
|---|---|---|
| `from` | Nagłówek From:, znormalizowany tak, jak normalizuje go lista blokowanych. | text |
| `from_domain` | Domena z From: oraz jej DOMENY NADRZĘDNE, aż do dwóch etykiet: wiadomość z mail.corp.example.com pasuje także do corp.example.com i example.com, a do com nie pasuje nic. | text |
| `envelope_from` | SMTP-owe MAIL FROM. Różne od from na każdej liście mailingowej i jedyna tożsamość, przeciwko której wolno napisać reject. | text |
| `to`, `cc`, `bcc` | Dowolny adres w tym nagłówku. | text |
| `recipient` | Dowolny adres w to, cc lub bcc: skrót na wszystkie trzy. | text |
| `reply_to` | Nagłówek Reply-To. | text |
| `delivered_to` | Kanoniczny adres, na który dostarczono tę kopię, z obciętym tagiem po plusie i zamieniony na małe litery — i tak właśnie dopasowuje się alias catch-all. | text |
| `subject` | Temat w postaci, w jakiej przyszedł. | text |
| `body` | Część tekstowa albo HTML sprowadzony do tekstu. Z limitem, więc treść o rozmiarze 20 MB nie jest skanowana w całości. | text |
| `header` | Dowolny nagłówek, wskazany w polu header samego warunku. Tam wymagany i sprowadzany do małych liter przed porównaniem. | text |
| `list_id` | Nagłówek List-Id: uchwyt, którym przedstawia się lista mailingowa. | text |
| `attachment_name` | Nazwa pliku dowolnego załącznika. | text |
| `attachment_type` | Typ MIME dowolnego załącznika, np. application/pdf. | text |
| `has_attachment` | Czy w ogóle jakiś jest. | equals "true" / "false" |
| `spam` | Werdykt spamowy, do jakiego doszła ścieżka doręczania, zanim zadziałały twoje reguły. | equals "true" / "false" |
| `attachment_size` | Rozmiar załącznika w bajtach. Porównanie pasuje, gdy spełnia je którykolwiek załącznik. | gt, lt, equals |
| `message_size` | Cała wiadomość na łączu, w bajtach. | gt, lt, equals |
| `hour` | Godzina nadejścia, 0–23, UTC. | gt, lt, equals |
| `weekday` | Dzień nadejścia, 0–6, niedziela to 0, UTC. | gt, lt, equals |
| Operator | Co robi |
|---|---|
| `matches` | Glob i tylko glob: * dla dowolnego ciągu znaków, ? dla jednego. Żadnych wyrażeń regularnych. Wzorzec od klienta API działa na ścieżce doręczania, a taki z katastrofalnym nawracaniem to skrzynka, która przestaje odbierać. |
| `contains` | Podciąg, bez rozróżniania wielkości liter. |
| `equals` | Cała wartość, bez rozróżniania wielkości liter. Na polu liczbowym — równość liczbowa. |
| `starts_with` | Przedrostek, bez rozróżniania wielkości liter. |
| `ends_with` | Przyrostek, bez rozróżniania wielkości liter. |
| `gt`, `lt` | Liczbowo, tylko na czterech polach liczbowych. Pole tekstowe z gt nigdy nie pasuje. |
Wzorzec matches musi nieść co najmniej dwa własne znaki alfanumeryczne — ten sam próg co na liście blokowanych. Samo * jest odrzucane przy zapisie, zamiast zostać przyjęte i po cichu pasować do każdej wiadomości, jaka kiedykolwiek przyjdzie, co jest awarią, a nie regułą.
Warunek, na który silnik nie umie odpowiedzieć (nieznane pole z nowszego klienta, wzorzec, który się nie skompiluje, contains ""), jest traktowany jak pytanie, którego nigdy nie zadano, a nie jak fałsz, i negate tego nie odwraca. To rozróżnienie jest nośne: zanegowany zepsuty warunek potraktowany jak fałsz odpalałby swoją regułę na każdej wiadomości w skrzynce. equals "" jest honorowane, bo „temat jest pusty” to prawdziwe pytanie.
Co może zrobić reguła
| Akcja | `value` | Co się dzieje |
|---|---|---|
| `label` | identyfikator etykiety | Dodaje etykietę. Identyfikatory USER_… pochodzą z GET /labels. |
| `remove_label` | identyfikator etykiety | Usuwa ją. Wskazanie tej samej etykiety w obu jest rozstrzygane przed zapisaniem wiadomości, a nie zostawione temu, co zadziałało jako ostatnie. |
| `archive` | brak | Wyjmuje ją ze skrzynki odbiorczej. |
| `mark_read` | brak | Zdejmuje UNREAD. |
| `star` | brak | Dodaje STARRED. |
| `spam` | brak | Odkłada ją do Spamu. |
| `trash` | brak | Odkłada ją do Kosza, zdejmując etykiety, których wiadomość w koszu nie zachowuje. |
| `forward` | adres | Wysyła kopię dalej. Przeczytaj notatkę poniżej, zanim tego użyjesz. |
| `reply` | identyfikator lub slug szablonu | Odpowiada automatycznie opublikowanym szablonem, z zastrzeżeniem opisanego niżej zabezpieczenia przed pętlą. |
| `block_sender` | brak | Dodaje nadawcę do listy blokowanych, więc następna wiadomość jest odrzucana już w drzwiach. |
| `reject` | brak | Odrzuca wiadomość na poziomie SMTP z 550 5.7.1 Message refused by the recipient. Tylko koperta. Patrz niżej. |
reject jest odrzucane przy zapisie, o ile ta sama reguła nie niesie przynajmniej jednego warunku envelope_from: reject_needs_envelope, 422. 550 odpowiada temu, kto podał nam wiadomość, a na liście mailingowej jest to LISTA, która odczytuje odmowę jako odbijającego się subskrybenta i wypisuje czytelnika z czegoś, gdzie chciał tylko, żeby jedna osoba przestała pisać. Nawet z zapisanym warunkiem dopasowanie, które wyszło wyłącznie z tożsamości nagłówkowych, schodzi do odłożenia w Spamie, bo koperta jest jedyną tożsamością, w którą odmowa może być uczciwie wycelowana.
Przekierowanie forward sterowane regułą wychodzi ścieżką wysyłkową, która PRZEBUDOWUJE wiadomość: oryginalny podpis DKIM tego nie przeżywa, podobnie jak egzotyczne części, nietypowe nagłówki czy cokolwiek powyżej limitu rozmiaru wychodzącego, który wiadomość 25 MB z załącznikami przekroczy. To kopia tego, co przyszło, a nie wiadomość, która przyszła. Adres jest sprawdzany przy zapisie reguły, więc niezweryfikowany cel to 422 na wywołaniu, a nie reguła, która po cichu gubi co dziesiątą wiadomość.
reply nie odpowie maszynie. Jest tłumione, gdy wiadomość niesie Auto-Submitted (inne niż no), Precedence: bulk|list|junk, List-Id, List-Unsubscribe, X-Autoreply albo X-Autorespond, gdy nadawca koperty jest pusty (kształt, jaki przyjmuje każde powiadomienie o niedoręczeniu) i gdy nagłówków w ogóle nie dało się odczytać. Do tego jeden nadawca dostaje najwyżej jedną autoodpowiedź na 24 godziny z danej skrzynki. Dwie skrzynki z regułami odpowiedzi i bez zabezpieczenia piszą do siebie, dopóki ktoś tego nie zauważy.