---
title: "Compile a rule description"
method: POST
path: "/email-rules/compile"
tags: ["Email Rules"]
---

# Compile a rule description

`POST /email-rules/compile`

## Request

- Base URL: `https://api.primitive.dev/v1`
- URL: `https://api.primitive.dev/v1/email-rules/compile`
- Auth: HTTP bearer

Turns a plain-English description of which received emails to match into a rule tree over the published column contract, with a plain-English explanation of what it matches, the assumptions made, and warnings for anything the columns cannot express. Where the columns fall short the rule may carry up to three yes/no questions, asked about an email only after its conditions match. Nothing is saved. The SQL the rule renders to is returned only when include_sql is true. Needs mail:read, a credential acting as a member with their full access (API keys, agent keys and narrowed tokens are refused), and the email rules feature on the organization.

## Headers

- `Idempotency-Key` string

## Request body

- CompileEmailRuleRequest
  - `english` string, required: What the rule should match, in plain English.
  - `include_sql` boolean: Also return the SQL the rule renders to. Off by default.

## Response `200`

Compile a rule description

- object
  - `success` true, required
  - `data` CompileEmailRuleResult, required
    - `tree` object, required
      - `version` 1, required
      - `vocabulary` string, required: The column contract version the rule is written against, for example v1.
      - `when` object, required: The rule's conditions: a condition ({column, op, value?, min_confidence?}) or a group ({all: [...]}, {any: [...]} or {not: ...}).
      - `questions` string[], required: Yes/no questions of the rule's own, asked about an email only after its conditions match. An email matches only if every answer is yes.
    - `explanation` string, required: What the rule matches, in plain English.
    - `assumptions` string[], required: Readings the compiler chose where the description was open to more than one.
    - `warnings` string[], required: Parts of the description the column contract cannot express, and how the rule handles them.
    - `compiled_by` string, required: The model that compiled the rule.
    - `sql` object: Present only when include_sql was true.
      - `expression` string, required: A parameterized boolean expression over one row per email.
      - `params` unknown[], required: The values bound to $1, $2 and so on.
        - unknown

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key
- `403`: Authenticated caller lacks permission for the operation
- `422`: email_rule_not_compiled: the description could not be turned into a valid rule (details.reason is refused, invalid or truncated).
- `429`: Rate limit exceeded. The `ratelimit-*` headers describe the limiter that rejected this request, with its own limit and window, not the API budget that successful responses report. A limiter that reports only a wait sends `Retry-After` alone.
- `503`: email_rule_compiler_unavailable: the rule compiler is not available or could not be reached.

---

[API](https://skmtc.dev/primitive/apis/primitive-api.md) - [All operations](https://skmtc.dev/primitive/apis/primitive-api/llms.txt) - [OpenAPI document](https://skmtc.dev/primitive/apis/primitive-api/revisions/bce409c97acb?raw)