# Create an auto-forward rule

Source: https://docs.maylee.app/api-reference/auto-forward-rules/create-auto-forward-rule

`POST https://api.maylee.app/api/v1/auto-forward-rules`

Scope: `write`. Also requires `allowOutboundSend` (the Send emails permission of the key).

Forwards every incoming email matching the condition to `forwardTo`.

A rule makes email leave the workspace: creating, changing or deleting one requires `allowOutboundSend` on the key, like sending does. A key with `write` alone gets `403 OUTBOUND_SEND_NOT_ALLOWED`.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | A unique value per operation, such as a UUID. Replays the stored response for 24h. Reusing a key with a different body returns 409. 0 to 255 characters. |

## Request body

`application/json`, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `conditionValue` | string | yes | The name of an AI label when `conditionField` is `label` (rules run when an email arrives, right after AI labeling, so a manual label never triggers them); otherwise the text to match, case-insensitively. 1 to 255 characters. |
| `forwardTo` | string (email) | yes | Destination address. 0 to 255 characters. |
| `conditionField` | string | no | What to match: `label` (an AI label), `sender_contains`, `sender_equals`, `subject_contains` or `subject_equals`. One of: `label`, `sender_contains`, `sender_equals`, `subject_contains`, `subject_equals`. Default: `"label"`. |
| `isActive` | boolean | no | An inactive rule is kept but forwards nothing. Default: `true`. |
| `mode` | string | no | `normal` forwards with the usual `Fwd:` subject and quoted body. `invisible` passes the email on unchanged, with `Reply-To` set to the original sender. One of: `normal`, `invisible`. Default: `"normal"`. |

## Example request

```bash
curl -X POST "https://api.maylee.app/api/v1/auto-forward-rules" \
  -H "Authorization: Bearer $MAYLEE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "conditionField": "label",
  "conditionValue": "Invoices",
  "forwardTo": "accounting@your-company.com",
  "mode": "normal"
}'
```

## Responses

### 201

Created.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rule` | AutoForwardRule | yes | Forwards matching incoming emails to an address. Managing rules requires `allowOutboundSend` on the key. |
| `rule.conditionField` | string | yes | One of: `label`, `sender_contains`, `sender_equals`, `subject_contains`, `subject_equals`. |
| `rule.conditionValue` | string | yes | A label name when `conditionField` is `label`, otherwise the text to match, case-insensitively. |
| `rule.createdAt` | string (date-time) | yes |  |
| `rule.forwardTo` | string (email) | yes |  |
| `rule.id` | string | yes |  |
| `rule.isActive` | boolean | yes |  |
| `rule.mode` | string | yes | `normal` forwards with the usual `Fwd:` subject and quoted body. `invisible` sends the original as is, with `Reply-To` set to the original sender. One of: `normal`, `invisible`. |
| `rule.updatedAt` | string (date-time) | yes |  |

```json
{
  "rule": {
    "conditionField": "label",
    "conditionValue": "Invoices",
    "createdAt": "2026-08-01T09:00:00.000Z",
    "forwardTo": "accounting@your-company.com",
    "id": "cmaf1a2b3c4d5e6f7g8h9i0j",
    "isActive": true,
    "mode": "normal",
    "updatedAt": "2026-08-01T09:00:00.000Z"
  }
}
```

### 400

Invalid payload: `forwardTo` must be an email address, `conditionValue` must not be empty.

### 401

Missing, malformed, revoked or expired API key.

### 403

Key lacks the required scope, or outbound sending is not enabled on it.

### 429

Per-minute rate limit (`RATE_LIMIT_EXCEEDED`) or monthly quota (`QUOTA_EXCEEDED`) exhausted.

Errors use the format `{ "code", "error", "details" }`: see [Errors](/errors.md).