Integration conditions

Integration conditions let you choose which integration sends a message when you have more than one active integration on the same channel. For example, you might send email for one tenant through their own SendGrid account, and send everyone else’s email through your default provider. Integration conditions only pick the provider. They don’t decide whether a step runs. If you want to skip a step, use step conditions. Some common reasons to use them:

Each tenant has its own email or SMS provider account.
You use different sender credentials for different locales or subscriber plans.
A chat connection, such as Slack or Teams, should only receive messages for a specific tenant.

Add conditions in the dashboard

Go to Integrations and open an integration, or add a new one.
In the side panel, click Integration conditions.
Add your rules using AND and OR groups, then click Done.
Save the integration.

The rule builder is the same one used for step conditions, so you can nest groups and use the same operators, such as equals, contains, in, and is empty.

An integration with conditions can’t be the primary integration. Saving conditions removes the primary flag, and marking an integration as primary removes its conditions. For email and SMS, keep one primary integration without conditions so Novu has something to fall back to.

If the integration still has conditions from the older dashboard, you’ll see a warning in the panel. Saving new conditions replaces the old ones.

How Novu picks the integration

Novu checks conditions at the moment the step sends a message, not when you save the integration. The behavior depends on the channel.

Email and SMS

Email and SMS send through one integration per message. Novu picks it in this order:

If the trigger passes integrationIdentifier in overrides.email or overrides.sms, Novu uses that integration. Conditions aren’t checked at all for that step, including any conditions on the integration you passed.
If the trigger doesn’t pass integrationIdentifier, Novu goes through the active integrations that have conditions, starting with the highest priority. When two have the same priority, the newer one goes first. The first integration whose conditions match sends the message.
If no conditions match, Novu uses the primary integration.

Active integrations that have no conditions and aren’t primary are never picked in steps 2 and 3. Here’s a trigger that sends email through a specific integration, no matter what conditions are set up:

await novu.trigger({
  workflowId: "invoice-paid",
  to: { subscriberId: "user-123" },
  overrides: {
    email: {
      integrationIdentifier: "sendgrid-acme",
    },
  },
});

If sendgrid-acme doesn’t exist or isn’t active, Novu doesn’t fall back to conditions or the primary integration. The step fails, and the activity feed shows that no active integration was found. For more on passing an integration in overrides, see Targeting a specific provider for email and Target a specific provider for SMS.

Chat and push

Chat and push can send through more than one integration for the same subscriber, so there’s no single integration to pick and no primary fallback. For chat connections stored as channel endpoints, such as Slack, Teams, and Telegram, Novu checks each integration before sending. Endpoints on integrations without conditions always receive the message. Endpoints on integrations whose conditions don’t match are skipped. If every integration has conditions and none match, nothing is sent. For push, and for older chat setups where the webhook URL or token is saved on the subscriber, Novu sends through whichever integration holds those credentials. Conditions on that integration don’t stop the send. If you don’t want a tenant to receive push or chat through an integration, don’t save their credentials on it. Passing integrationIdentifier in the email or SMS overrides has no effect on chat. Chat endpoints still go through their own condition checks.

What conditions can use

Conditions can read subscriber, context, and workflow data. They can’t use payload values or results from earlier steps. If you need those, use step conditions instead. Integrations that already had payload.* rules saved before this change will keep working, but you can’t add new ones. These fields are available in the dashboard:

Field	Example use
`context.tenant.id`	Send through a tenant’s own provider account
`subscriber.subscriberId`	Use an integration for one specific subscriber
`subscriber.email`, `subscriber.phone`	Match on contact details
`subscriber.firstName`, `subscriber.lastName`	Match on name
`subscriber.locale`	Pick a provider by language or region
`subscriber.data`	Match custom attributes, such as `subscriber.data.plan`
`workflow.workflowId`	Pick a provider for a specific workflow
`workflow.name`	Match on the workflow name
`workflow.description`	Match on the workflow description
`workflow.tags`	Match on workflow tags, using operators like contains any of
`workflow.severity`	Pick a provider by workflow severity

You can also use other context.* and subscriber.* paths, like context.tenant.data.plan or subscriber.data.region. Payload paths and workflow.* fields not listed above are rejected. To set context.tenant.id, pass a tenant in the trigger’s context:

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

Passing "acme-corp" or { id: "acme-corp" } both set context.tenant.id to acme-corp. See Contexts and Multi-tenancy for more.

Example: a separate email provider for one tenant

Say your default email provider is SendGrid, and your customer Acme wants their emails sent from their own account.

Keep your default SendGrid integration active and primary, with no conditions.
Add a second email integration using Acme’s credentials. Don’t make it primary.
Open Integration conditions on the Acme integration and add context.tenant.id equals acme-corp.
Trigger your workflow with context: { tenant: "acme-corp" }. Those emails go through Acme’s integration, and everything else goes through your default SendGrid integration.

Manage conditions with the API

Conditions are saved as JSON Logic in the integration’s rules field. You can set rules when you create or update an integration with the Integrations API.

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

The API accepts the same fields as the dashboard. Payload paths and unknown workflow.* fields are rejected. Updating an integration with rules removes its primary flag and replaces any older conditions. Creating an integration is different. If it’s the first active email or SMS integration in the environment, Novu can still make it primary even if you pass rules. When that happens and the rules don’t match, Novu still sends through it as the primary fallback. To avoid this, create your primary integration first without conditions, then add the integrations that have conditions.

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 picks the integration

Email and SMS

Chat and push

What conditions can use

Example: a separate email provider for one tenant

Manage conditions with the API

Integrations

Step conditions

Contexts

Multi-tenancy

​Add conditions in the dashboard

​How Novu picks the integration

​Email and SMS

​Chat and push

​What conditions can use

​Example: a separate email provider for one tenant

​Manage conditions with the API

​Related

Integrations

Step conditions

Contexts

Multi-tenancy

Add conditions in the dashboard

How Novu picks the integration

Email and SMS

Chat and push

What conditions can use

Example: a separate email provider for one tenant

Manage conditions with the API

Related