Tạo quy tắc
Điều kiện ở một bên, hành động ở bên kia. Được bật trừ khi bạn chỉ định khác.
Chạy lệnh gọi thật với không gian làm việc của bạn, bằng khóa của chính bạn.
POST /rules
Điều kiện ở một bên, hành động ở bên kia. Được bật trừ khi bạn chỉ định khác.
Ví dụ
Cần rules:write. Trả về 201. position không được chấp nhận. Quy tắc mới được thêm vào cuối danh sách, và để di chuyển nó hãy dùng 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"}Quy tắc được tạo ở đây sẽ BẬT, và bắt đầu tác động từ thư tiếp theo. Đó là mặc định đúng cho một lệnh gọi mà ai đó thực hiện có chủ đích, và ngược lại với công cụ MCP createRule, công cụ ghi cùng quy tắc đó ở trạng thái TẮT vì một mô hình quyết định lưu trữ thư không nên để quy tắc lưu trữ thư trước khi có người đọc lại quy tắc đó.
Một name trùng lặp trên cùng kết nối là rule_name_taken, mã 409. Tên là cách nhận diện quy tắc trong nhật ký chạy và trên màn hình cài đặt, nên hai quy tắc cùng tên "Newsletters" tạo ra một báo cáo mà không ai đọc được.
Quy tắc thứ 101 là rule_limit_reached, mã 422. Giới hạn này là để chống một script chạy trong vòng lặp chứ không phải một ranh giới tính phí, và không được khóa. Hai lệnh tạo chạy đua ở mốc 99 có thể cùng thành công.
Điều kiện có thể hỏi gì
Một điều kiện là { field, op, value }, với header tùy chọn chỉ định header cần đọc và negate tùy chọn. value LUÔN là string khi truyền đi. Các trường số được so sánh như số sau Number(value), và hai trường boolean nhận các chuỗi nguyên văn "true" và "false", vì một trường với một kiểu là schema mà trình tạo OpenAPI có thể mô tả, còn một union ba kiểu thì không.
| Trường | Đọc | Toán tử |
|---|---|---|
| `from` | Header From:, được chuẩn hóa theo cùng cách danh sách chặn chuẩn hóa nó. | văn bản |
| `from_domain` | Tên miền của From: và các tên miền CHA của nó, xuống đến hai nhãn: một thư từ mail.corp.example.com cũng khớp corp.example.com và example.com, và không khớp gì với com. | văn bản |
| `envelope_from` | MAIL FROM của SMTP. Khác với from trên mọi danh sách thư, và là danh tính duy nhất mà một reject có thể được viết dựa vào. | văn bản |
| `to`, `cc`, `bcc` | Bất kỳ một địa chỉ nào trong header đó. | văn bản |
| `recipient` | Bất kỳ địa chỉ nào trong to, cc hoặc bcc: cách viết tắt cho cả ba. | văn bản |
| `reply_to` | Header Reply-To. | văn bản |
| `delivered_to` | Địa chỉ chuẩn mà bản sao này được chuyển đến, đã bỏ plus-tag và chuyển thành chữ thường, đó là cách một alias catch-all được so khớp. | văn bản |
| `subject` | Dòng tiêu đề như khi nhận được. | văn bản |
| `body` | Phần văn bản, hoặc HTML được rút gọn thành văn bản. Có giới hạn, nên một body 20 MB sẽ không bị quét toàn bộ. | văn bản |
| `header` | Bất kỳ header nào, được chỉ định trong trường header của chính điều kiện. Bắt buộc ở đó và được chuyển thành chữ thường trước khi so sánh. | văn bản |
| `list_id` | Header List-Id: định danh mà một danh sách thư dùng để tự nhận diện. | văn bản |
| `attachment_name` | Tên tệp của bất kỳ tệp đính kèm nào. | văn bản |
| `attachment_type` | Kiểu MIME của bất kỳ tệp đính kèm nào, ví dụ application/pdf. | văn bản |
| `has_attachment` | Có tệp đính kèm nào hay không. | equals "true" / "false" |
| `spam` | Kết luận spam mà đường nhận thư đưa ra, trước khi các quy tắc của bạn chạy. | equals "true" / "false" |
| `attachment_size` | Kích thước của một tệp đính kèm tính bằng byte. Phép so sánh khớp khi bất kỳ tệp đính kèm nào thỏa mãn nó. | gt, lt, equals |
| `message_size` | Toàn bộ thư khi truyền đi, tính bằng byte. | gt, lt, equals |
| `hour` | Giờ nhận, 0–23, UTC. | gt, lt, equals |
| `weekday` | Ngày nhận, 0–6, Chủ nhật là 0, UTC. | gt, lt, equals |
| Toán tử | Chức năng |
|---|---|
| `matches` | Một glob, và chỉ glob: * cho một chuỗi ký tự bất kỳ, ? cho một ký tự. Không có biểu thức chính quy. Mẫu từ một API client chạy trên đường nhận thư, và một mẫu backtracking thảm họa ở đó là một hộp thư ngừng nhận thư. |
| `contains` | Chuỗi con, không phân biệt hoa thường. |
| `equals` | Toàn bộ giá trị, không phân biệt hoa thường. Trên trường số, là so sánh bằng về số. |
| `starts_with` | Tiền tố, không phân biệt hoa thường. |
| `ends_with` | Hậu tố, không phân biệt hoa thường. |
| `gt`, `lt` | So sánh số, chỉ trên bốn trường số. Một trường văn bản với gt không bao giờ khớp. |
Một mẫu matches phải chứa ít nhất hai ký tự chữ-số của riêng nó, cùng ngưỡng mà danh sách chặn áp dụng. Một * đơn lẻ bị từ chối khi ghi thay vì được chấp nhận rồi lặng lẽ khớp với mọi thư sẽ đến, đó là một sự cố chứ không phải một quy tắc.
Một điều kiện mà engine không thể trả lời (một trường không xác định từ client mới hơn, một mẫu không biên dịch được, contains "") được coi là một câu hỏi chưa từng được đặt ra thay vì là false, và negate không đảo ngược nó. Sự phân biệt đó rất quan trọng: một điều kiện hỏng bị phủ định mà được coi là false sẽ kích hoạt quy tắc của nó trên mọi thư trong hộp thư. equals "" được chấp nhận, vì "dòng tiêu đề trống" là một câu hỏi thực sự.
Quy tắc có thể làm gì
| Hành động | `value` | Điều gì xảy ra |
|---|---|---|
| `label` | một id nhãn | Thêm nhãn. Các id USER_… lấy từ GET /labels. |
| `remove_label` | một id nhãn | Xóa nhãn. Việc chỉ định cùng một nhãn ở cả hai được giải quyết trước khi thư được phân loại thay vì để cho hành động chạy sau cùng quyết định. |
| `archive` | không có | Chuyển thư ra khỏi hộp thư đến. |
| `mark_read` | không có | Bỏ UNREAD. |
| `star` | không có | Thêm STARRED. |
| `spam` | không có | Chuyển thư vào Spam. |
| `trash` | không có | Chuyển thư vào Thùng rác, xóa các nhãn mà một thư trong thùng rác không giữ lại. |
| `forward` | một địa chỉ | Gửi tiếp một bản sao. Hãy đọc ghi chú bên dưới trước khi sử dụng. |
| `reply` | một id hoặc slug của mẫu | Tự động trả lời bằng một mẫu đã xuất bản, tuân theo cơ chế chống vòng lặp bên dưới. |
| `block_sender` | không có | Thêm người gửi vào danh sách chặn, để thư tiếp theo bị từ chối ngay từ cửa. |
| `reject` | không có | Từ chối thư ở thời điểm SMTP với 550 5.7.1 Message refused by the recipient. Chỉ dựa trên envelope. Xem bên dưới. |
reject bị từ chối khi ghi trừ khi cùng quy tắc có ít nhất một điều kiện envelope_from: reject_needs_envelope, mã 422. Mã 550 phản hồi cho bất kỳ ai đã chuyển thư đến cho chúng tôi, và trên một danh sách thư thì đó là DANH SÁCH, vốn hiểu lời từ chối là một người đăng ký bị trả thư và hủy đăng ký người đọc khỏi thứ mà họ chỉ muốn một người ngừng đăng bài. Ngay cả khi đã viết điều kiện, một lần khớp chỉ đến từ danh tính trong header sẽ bị hạ cấp thành chuyển vào Spam, vì envelope là danh tính duy nhất mà một lời từ chối có thể nhắm đến một cách trung thực.
Một forward do quy tắc kích hoạt được gửi đi qua đường gửi, vốn XÂY DỰNG LẠI thư: chữ ký DKIM gốc không được giữ lại, và các phần lạ, header bất thường hay bất cứ thứ gì vượt quá mức trần kích thước gửi đi cũng vậy, điều mà một thư 25 MB có tệp đính kèm sẽ vượt quá. Đó là bản sao của những gì đã đến chứ không phải chính thư đã đến. Địa chỉ được kiểm tra khi quy tắc được ghi, nên một đích chưa xác minh sẽ là lỗi 422 trên lệnh gọi thay vì một quy tắc lặng lẽ làm rơi mỗi thư thứ mười.
reply sẽ không trả lời máy. Nó bị chặn khi thư có Auto-Submitted (khác no), Precedence: bulk|list|junk, List-Id, List-Unsubscribe, X-Autoreply hoặc X-Autorespond, khi người gửi envelope trống (hình dạng của mọi thư bị trả lại) và khi hoàn toàn không đọc được header. Ngoài ra, một người gửi nhận tối đa một thư tự động trả lời mỗi 24 giờ từ một hộp thư nhất định. Hai hộp thư có quy tắc trả lời mà không có cơ chế bảo vệ sẽ gửi thư qua lại cho nhau cho đến khi có người nhận ra.