Create a rule - Rules - API Reference

POST

https://api.us.nylas.com/v3/rules

Creates a rule for your application. A rule defines a trigger (inbound or outbound), conditions against sender or recipient fields, and actions to apply when the conditions match. Inbound rules run on incoming messages; outbound rules run on sends before they're submitted to the email provider. Inbound and outbound rules are isolated — inbound rules never run during sends, and outbound rules never run on message receipt.

Inbound rules can match from.address, from.domain, or from.tld. Outbound rules can match from.address, from.domain, from.tld, recipient.address, recipient.domain, recipient.tld, or outbound.type (compose or reply). Link inbound rules to a policy to apply them to specific Agent Accounts. Outbound rules are currently evaluated from the sending application's enabled outbound rules.

The application_id and organization_id are derived from your API key and are read-only.

NYLAS API KEY

Request body

name*string

A human-readable name for the rule.

Example: "Block spam domains"

descriptionstring

Example: "Rejects messages from known spam domains at the SMTP level."

priorityinteger

Default: 10

Example: 1

min: 0max: 1000

enabledboolean

Default: true

Example: true

triggerstring

When the rule is evaluated. inbound runs the rule on incoming messages; outbound runs the rule on sends before they're submitted to the email provider. Inbound rules accept only from.* conditions. Outbound rules accept from.*, recipient.*, and outbound.type.

inboundoutbound

Default: "inbound"

Example: "inbound"

match*object

actions*array<object>

minItems: 1

Responses

request_idstring

ID of the request.

Example: "5fa64c92-e840-4357-86b9-2aa364d35b88"

dataobject

idstring

Globally unique identifier for the rule (UUID).

Example: "c1d2e3f4-5678-4abc-9def-0123456789ab"

namestring

A human-readable name for the rule. Required on create.

Example: "Block spam domains"

descriptionstring

An optional description of what the rule does.

Example: "Rejects messages from known spam domains at the SMTP level."

priorityinteger

Execution order for the rule. Lower numbers run first. Must be between 0 and 1000. Defaults to 10.

Default: 10

Example: 1

min: 0max: 1000

enabledboolean

Whether the rule is active. Defaults to true.

Default: true

Example: true

triggerstring

When the rule is evaluated. inbound rules run on incoming messages. outbound rules run on sends before the message is submitted to the email provider — an outbound rule with a block action rejects the send with HTTP 403 and no message is delivered. Non-blocking actions (mark_as_spam, archive, mark_as_read, mark_as_starred, assign_to_folder, trash) on outbound rules apply to the stored sent copy. Inbound and outbound rules are isolated: inbound rules never run during sends, and outbound rules never run on receipt.

inboundoutbound

Default: "inbound"

Example: "inbound"

matchobject

Defines the conditions that must be met for the rule to apply.

actionsarray<object>

The actions to perform when the rule matches. At least one action is required. The block action cannot be combined with other actions — it is terminal.

application_idstring

The ID of the application that owns the rule. Read-only; derived from the authenticated API key.

Example: "ad410018-d306-43f9-8361-fa5d7b2172e0"

organization_idstring

The ID of the Nylas organization that owns the rule. Read-only; derived from the authenticated API key.

Example: "org-abc123"

created_atinteger

When the rule was created, in seconds using the Unix timestamp format.

Example: 1742932766

updated_atinteger

When the rule was last updated, in seconds using the Unix timestamp format.

Example: 1742932766