Integration conditions

Integration conditions decide which provider integration sends a notification. They do not skip workflow steps. To skip a step, use step conditions instead. Use integration conditions when you run more than one active integration for the same channel and want Novu to pick one at send time. Typical cases:

A separate email or SMS provider account per tenant
Different sender credentials by locale or subscriber plan
Endpoint-based chat connections that should only send for matching tenants

Add conditions in the dashboard

Open Integrations and select an existing integration, or add a new provider.
In the integration side panel, click Integration conditions.
Add rules with AND / OR, then click Done.
Save the integration.

The same rule builder is used for step conditions. You can nest groups and compare fields with equals, contains, in, empty, and the other operators listed on that page.

In the dashboard, an integration with conditions cannot be primary. Saving conditions unsets the primary flag. Making an integration primary removes its conditions. Keep a separate unconditioned primary integration as the email and SMS fallback.

If an integration still has legacy conditions from the previous dashboard, the editor shows a warning. Saving new conditions in this panel replaces those legacy rules.

How Novu selects an integration

Conditions are evaluated when the channel step sends, not when you save the integration.

Email and SMS

If the trigger sets integrationIdentifier (or an equivalent channel override), Novu uses that integration and does not evaluate conditions. See Targeting a specific provider and Target a specific provider.
Otherwise Novu considers only active integrations that have conditions. It uses the first match, in priority order, then newest first. Unconditioned integrations other than primary are not in this scan.
If none match, Novu uses the primary integration.

Chat and push

These channels can deliver through more than one active integration at a time. Conditions do not replace email and SMS selection. Endpoint-based chat (Slack, Teams, Telegram, and other connections stored as channel endpoints): Novu keeps endpoints whose integration has no conditions, and drops endpoints whose conditions do not match. There is no primary fallback. If every remaining integration is conditioned and none match, nothing is sent on those endpoints. Push and legacy chat (device tokens, webhook URLs, and other credentials stored on the subscriber): Novu sends through the integration those credentials are stored on. Conditions on that integration are not used to skip the send. Do not use integration conditions to suppress push or legacy chat for a tenant; store credentials on the integration you want to send through. Pinning integrationIdentifier on the trigger skips the email and SMS condition scan. Endpoint-based chat still evaluates conditions on each integration’s endpoints.

Data available in conditions

Integration conditions can read subscriber and context values only. They cannot read the trigger payload, workflow metadata, or previous step results. Those belong on step conditions. The dashboard field picker includes:

Field	Typical use
`context.tenant.id`	Route to a tenant-specific provider account
`subscriber.subscriberId`	Pin an integration to a specific recipient
`subscriber.email`, `subscriber.phone`	Match on contact details
`subscriber.firstName`, `subscriber.lastName`	Match on profile name
`subscriber.locale`	Route by language or region
`subscriber.data`	Match custom subscriber attributes such as `subscriber.data.plan`

You can also reference other context.* and subscriber.* paths, for example context.tenant.data.plan or subscriber.data.region. To populate context.tenant.id, pass a tenant context on the trigger:

await novu.trigger({
  workflowId: "invoice-paid",
  to: { subscriberId: "user-123" },
  context: {
    tenant: "acme-corp",
  },
});

A string value such as "acme-corp" and { id: "acme-corp" } both set context.tenant.id to acme-corp. See Contexts and Multi-tenancy.

Example: tenant-specific email provider

Keep your default SendGrid (or other) integration active and primary, with no conditions.
Add a second email integration for tenant Acme. Do not mark it primary.
Open Integration conditions and add context.tenant.id equals acme-corp.
Trigger with context: { tenant: "acme-corp" } to send through the Acme integration. Triggers without that tenant use the primary integration.

Manage conditions with the API

The dashboard stores conditions as JSON Logic on the integration rules field. Create or update an integration with the Integrations API and pass rules. Updating with rules unsets primary and replaces legacy conditions. Creating the first active email or SMS integration can still mark it as primary even when rules are present. If those rules do not match, the selector still uses that integration as the primary fallback. Prefer a separate unconditioned primary integration, then add conditioned integrations from the dashboard or the update API.

{
  "and": [
    { "==": [{ "var": "context.tenant.id" }, "acme-corp"] },
    { "==": [{ "var": "subscriber.locale" }, "fr"] }
  ]
}

Allowed variables are the same context.* and subscriber.* paths as in the dashboard. Payload fields are rejected.

Integrations

How integrations, primary, and active flags work

Step conditions

Skip or run workflow steps based on payload and subscriber data

Contexts

Pass tenant and other context on the trigger

Multi-tenancy

Isolate Inbox, preferences, and providers per tenant

Getting Started

Integrate <Inbox />

Integrate <Subscription />

Build a Workflow

Integrate Channels Providers

SDKs

Developer

Account

Build with AI

Additional Resources

Integration conditions

Add conditions in the dashboard

How Novu selects an integration

Email and SMS

Chat and push

Data available in conditions

Example: tenant-specific email provider

Manage conditions with the API

Integrations

Step conditions

Contexts

Multi-tenancy

​Add conditions in the dashboard

​How Novu selects an integration

​Email and SMS

​Chat and push

​Data available in conditions

​Example: tenant-specific email provider

​Manage conditions with the API

​Related

Integrations

Step conditions

Contexts

Multi-tenancy

Add conditions in the dashboard

How Novu selects an integration

Email and SMS

Chat and push

Data available in conditions

Example: tenant-specific email provider

Manage conditions with the API

Related