Criar uma regra
Condições de um lado, ações do outro. Ativa, a menos que diga o contrário.
Executa a chamada real contra o seu espaço de trabalho, com a sua própria chave.
POST /rules
Condições de um lado, ações do outro. Ativa, a menos que diga o contrário.
Exemplo
Requer rules:write. Devolve 201. position não é aceite. Uma regra nova é acrescentada ao fim da lista, e movê-la é 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"}Uma regra criada aqui está LIGADA, e começa a atuar na mensagem seguinte. É o comportamento certo por omissão para uma chamada que alguém fez deliberadamente, e é o oposto da ferramenta MCP createRule, que escreve a mesma regra DESATIVADA porque um modelo que decide arquivar correio não deve começar a arquivar antes de uma pessoa ter lido a regra.
Um name duplicado na mesma ligação é rule_name_taken, um 409. Os nomes são como uma regra é reconhecida num registo de execuções e no ecrã de definições, por isso duas regras chamadas "Newsletters" são um relatório que ninguém consegue ler.
A 101.ª regra é rule_limit_reached, um 422. O limite é uma proteção contra um script em ciclo e não uma fronteira contabilística, e não é bloqueante. Duas criações em corrida aos 99 podem ambas ter sucesso.
O que uma condição pode perguntar
Uma condição é { field, op, value }, com um header opcional a nomear que cabeçalho ler e um negate opcional. value é SEMPRE uma string no fio. Os campos numéricos são comparados como números depois de Number(value), e os dois campos booleanos aceitam literalmente as strings "true" e "false", porque um campo com um tipo é um esquema que um gerador OpenAPI consegue descrever e uma união de três não é.
| Campo | Lê | Operadores |
|---|---|---|
| `from` | O cabeçalho From:, normalizado como a lista de bloqueio normaliza. | texto |
| `from_domain` | O domínio de From: e os seus PAIS, até dois rótulos: uma mensagem de mail.corp.example.com corresponde também a corp.example.com e a example.com, e não corresponde a nada para com. | texto |
| `envelope_from` | O MAIL FROM de SMTP. Diferente de from em todas as listas de distribuição, e a única identidade contra a qual um reject pode ser escrito. | texto |
| `to`, `cc`, `bcc` | Qualquer um dos endereços nesse cabeçalho. | texto |
| `recipient` | Qualquer endereço em to, cc ou bcc: a abreviatura para os três. | texto |
| `reply_to` | O cabeçalho Reply-To. | texto |
| `delivered_to` | O endereço canónico para o qual esta cópia foi entregue, sem a etiqueta depois do sinal de mais e em minúsculas, que é como um alias catch-all é correspondido. | texto |
| `subject` | A linha de assunto tal como chegou. | texto |
| `body` | A parte de texto, ou o HTML reduzido a texto. Limitado, para que um corpo de 20 MB não seja percorrido por inteiro. | texto |
| `header` | Qualquer cabeçalho, nomeado no campo header da própria condição. Obrigatório aí e passado a minúsculas antes da comparação. | texto |
| `list_id` | O cabeçalho List-Id: o identificador por que uma lista de distribuição se apresenta. | texto |
| `attachment_name` | O nome de ficheiro de qualquer anexo. | texto |
| `attachment_type` | O tipo MIME de qualquer anexo, p. ex. application/pdf. | texto |
| `has_attachment` | Se existe algum, de todo. | equals "true" / "false" |
| `spam` | O veredicto de spam a que o caminho de entrega chegou, antes de as suas regras correrem. | equals "true" / "false" |
| `attachment_size` | O tamanho de um anexo em bytes. Uma comparação corresponde quando um qualquer anexo a satisfaz. | gt, lt, equals |
| `message_size` | A mensagem inteira no fio, em bytes. | gt, lt, equals |
| `hour` | Hora de chegada, 0–23, UTC. | gt, lt, equals |
| `weekday` | Dia de chegada, 0–6, domingo é 0, UTC. | gt, lt, equals |
| Operador | O que faz |
|---|---|
| `matches` | Um glob, e só um glob: * para qualquer sequência de caracteres, ? para um. Sem expressões regulares. Um padrão vindo de um cliente da API corre no caminho de entrega, e um com backtracking catastrófico ali é uma caixa de correio que deixa de receber. |
| `contains` | Subcadeia, sem distinção entre maiúsculas e minúsculas. |
| `equals` | O valor inteiro, sem distinção entre maiúsculas e minúsculas. Num campo numérico, igualdade numérica. |
| `starts_with` | Prefixo, sem distinção entre maiúsculas e minúsculas. |
| `ends_with` | Sufixo, sem distinção entre maiúsculas e minúsculas. |
| `gt`, `lt` | Numéricos, e apenas nos quatro campos numéricos. Um campo de texto com gt nunca corresponde. |
Um padrão matches tem de ter pelo menos dois caracteres alfanuméricos próprios, o mesmo limite que a lista de bloqueio aplica. Um * isolado é recusado na escrita em vez de aceite e depois a corresponder em silêncio a todas as mensagens que alguma vez chegarem, o que é uma avaria e não uma regra.
Uma condição a que o motor não sabe responder (um campo desconhecido vindo de um cliente mais recente, um padrão que não compila, contains "") é tratada como uma pergunta que nunca foi feita e não como false, e negate não a inverte. Essa distinção é estrutural: uma condição avariada e negada tratada como false dispararia a sua regra em todas as mensagens da caixa de correio. equals "" é respeitado, porque "a linha de assunto está vazia" é uma pergunta real.
O que uma regra pode fazer
| Ação | `value` | O que acontece |
|---|---|---|
| `label` | um id de etiqueta | Acrescenta a etiqueta. Os ids USER_… vêm de GET /labels. |
| `remove_label` | um id de etiqueta | Remove-a. Nomear a mesma etiqueta nas duas é resolvido antes de a mensagem ser arquivada, em vez de ficar dependente de qual correu por último. |
| `archive` | nenhum | Arquiva-a fora da caixa de entrada. |
| `mark_read` | nenhum | Retira UNREAD. |
| `star` | nenhum | Acrescenta STARRED. |
| `spam` | nenhum | Arquiva-a em Spam. |
| `trash` | nenhum | Arquiva-a em Trash, limpando as etiquetas que uma mensagem no lixo não conserva. |
| `forward` | um endereço | Envia uma cópia adiante. Leia a nota abaixo antes de o usar. |
| `reply` | um id ou slug de modelo | Responde automaticamente com um modelo publicado, sujeito à proteção contra ciclos descrita abaixo. |
| `block_sender` | nenhum | Acrescenta o remetente à lista de bloqueio, para que a mensagem seguinte seja recusada logo à porta. |
| `reject` | nenhum | Recusa a mensagem em tempo de SMTP com 550 5.7.1 Message refused by the recipient. Só envelope. Ver abaixo. |
reject é recusado na escrita a menos que a mesma regra tenha pelo menos uma condição envelope_from: reject_needs_envelope, um 422. Um 550 responde a quem nos entregou a mensagem, e numa lista de distribuição isso é a LISTA, que lê a recusa como um subscritor a devolver correio e cancela a subscrição do leitor a algo de que ele só queria que uma pessoa deixasse de publicar. Mesmo com a condição escrita, uma correspondência que tenha vindo apenas das identidades do cabeçalho é despromovida para arquivo em Spam, porque o envelope é a única identidade a que uma recusa pode ser honestamente dirigida.
Um forward conduzido por uma regra sai pelo caminho de envio, que RECONSTRÓI a mensagem: a assinatura DKIM original não sobrevive, e também não sobrevivem partes exóticas, cabeçalhos invulgares ou o que exceda o tecto de tamanho de saída, que uma mensagem de 25 MB com anexos vai exceder. É uma cópia do que chegou e não a mensagem que chegou. O endereço é verificado quando a regra é escrita, por isso um destino não verificado é um 422 na chamada e não uma regra que descarta em silêncio uma mensagem em cada dez.
reply não responde a uma máquina. É suprimido quando a mensagem traz Auto-Submitted (diferente de no), Precedence: bulk|list|junk, List-Id, List-Unsubscribe, X-Autoreply ou X-Autorespond, quando o remetente de envelope está vazio (a forma que todas as devoluções tomam) e quando os cabeçalhos não puderam sequer ser lidos. Além disso, cada remetente recebe no máximo uma resposta automática por 24 horas de uma dada caixa de correio. Duas caixas de correio com regras de resposta e sem proteção escrevem uma à outra até alguém dar por isso.