E-mail - Novu

Email providers are the services that deliver notifications to your subscribers’ email. You must set up each provider individually in the Novu dashboard to enable delivery through the Email channel. Novu provides a unified integration layer that connects your workflows to these email providers. Once you’ve added your integrations, Novu handles routing and delivery automatically, sending each email through the correct provider without requiring additional setup. This allows you to manage multiple email integrations and switch providers when needed.

Key features

Multi-provider support: Integrate any major provider like SendGrid, SES, or Mailgun.
Failover mechanisms: Automatically retry with a backup provider to ensure reliability.
Activity tracking: Track delivery status, open rates, and more in the Novu dashboard. See Activity Tracking.

Email Activity Tracking is available on Novu Cloud and Enterprise self-hosted only. It is not included in Community self-hosted edition. See Activity Tracking for more information.

How email works in Novu

Here’s the typical flow for sending an email notification through Novu:

Add an email provider

Start by adding an email provider in the Integration Store on your Novu dashboard. You can connect one or more integrations for different or the same providers.To learn how to add an email provider, refer to the guide for the supported providers.

Add the Email channel to your workflow

Next, include an Email step in a workflow. This step defines when and how an email should be sent as part of your notification workflow.

Define the email content

Within the Email step, you can design your message using the built-in visual editor or code editor. Novu supports dynamic data from your payload, so each message can be personalized for the subscriber.

Store subscriber email addresses

Novu automatically sends the notification to the email address stored on the subscriber’s profile. This profile is update either using the Novu dashboard or API.

Trigger the workflow

Trigger the workflow from your application code by sending an event to Novu. Novu automatically:

Resolves the subscriber.
Selects the correct provider.
Renders the email template.
Delivers the message through the configured email integration.

Learn how to build email template using the block editor, custom HTML, and dynamic variables.

Configuring email providers

When you add an email provider in the Integration Store, you configure settings that are common to all email providers, as well as credentials specific to that provider.

Default sender settings

Novu asks for two default settings for any email provider you connect:

Sender name: The name that appears in the recipient’s “From” field.
From email address: The email address the notification is sent from. For some email providers, including SendGrid, you must authenticate the From email address to make sure you’re sending an email from an authorized address.

These are the default values used for every email sent via this integration. You can override them when triggering a workflow if needed.

Provider authentication

You must provide credentials specific to your email provider for a successful integration.

For detailed setup guides for each integration, refer to the Supported Providers list at the bottom of this page.

Advanced email features

You can control advanced email features at runtime by passing data in your trigger call. This lets you send attachments, override default settings, or target a specific provider for a single notification.

Sending attachments

You can send attachments by passing an attachments array in the payload of your trigger. The attachment file can be provided as a buffer or a base64 encoded string. There is a total limit of 20MB for all attachments included in an email.

import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Required if using EU region
  // serverURL: "https://eu.api.novu.co",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
  },
  payload: {
    attachments: [
      {
        // buffer format
        file: fs.readFileSync(__dirname + '/data/novu.jpeg'),
        name: 'novu.jpeg',
        mime: 'image/jpeg',
      },
      {
        // base64 format
        file: 'iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mNkYPhfz0AEYBxVSF+FAP5FDvcfRYWgAAAAAElFTkSuQmCC',
        name: 'blue.png',
        mime: 'image/png',
      }
    ],
  },
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflowId",
        to={"subscriber_id": "subscriberId"},
        payload={
            "attachments": [
                {
                    "file": "iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mNkYPhfz0AEYBxVSF+FAP5FDvcfRYWgAAAAAElFTkSuQmCC",
                    "name": "blue.png",
                    "mime": "image/png",
                },
                {
                    "file": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII",
                    "name": "transparent.png",
                    "mime": "image/png",
                },
            ],
        },
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

_, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflowId",
    To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
        SubscriberID: "subscriberId",
    }),
    Payload: map[string]any{
        "attachments": []map[string]any{
            {
                "file": "iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mNkYPhfz0AEYBxVSF+FAP5FDvcfRYWgAAAAAElFTkSuQmCC",
                "name": "blue.png",
                "mime": "image/png",
            },
            {
                "file": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII",
                "name": "transparent.png",
                "mime": "image/png",
            },
        },
    },
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity('<NOVU_SECRET_KEY>')
    ->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflowId',
        to: new Components\SubscriberPayloadDto(subscriberId: 'subscriberId'),
        payload: [
            'attachments' => [
                [
                    'file' => 'iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mNkYPhfz0AEYBxVSF+FAP5FDvcfRYWgAAAAAElFTkSuQmCC',
                    'name' => 'blue.png',
                    'mime' => 'image/png',
                ],
                [
                    'file' => 'iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII',
                    'name' => 'transparent.png',
                    'mime' => 'image/png',
                ],
            ],
        ],
    ),
);

using Novu;
using Novu.Models.Components;
using System.Collections.Generic;

var sdk = new NovuSDK(secretKey: "<NOVU_SECRET_KEY>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflowId",
    To = To.CreateSubscriberPayloadDto(new SubscriberPayloadDto() {
        SubscriberId = "subscriberId",
    }),
    Payload = new Dictionary<string, object>() {
        { "attachments", new List<Dictionary<string, object>>() {
            new Dictionary<string, object>() {
                { "file", "iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mNkYPhfz0AEYBxVSF+FAP5FDvcfRYWgAAAAAElFTkSuQmCC" },
                { "name", "blue.png" },
                { "mime", "image/png" },
            },
            new Dictionary<string, object>() {
                { "file", "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII" },
                { "name", "transparent.png" },
                { "mime", "image/png" },
            },
        } },
    },
});

import co.novu.Novu;
import co.novu.models.components.*;
import java.util.List;
import java.util.Map;

Novu novu = Novu.builder()
    .secretKey("<NOVU_SECRET_KEY>")
    .build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflowId")
        .to(To2.of(SubscriberPayloadDto.builder()
            .subscriberId("subscriberId")
            .build()))
        .payload(Map.of(
            "attachments", List.of(
                Map.of(
                    "file", "iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mNkYPhfz0AEYBxVSF+FAP5FDvcfRYWgAAAAAElFTkSuQmCC",
                    "name", "blue.png",
                    "mime", "image/png"),
                Map.of(
                    "file", "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII",
                    "name", "transparent.png",
                    "mime", "image/png"))))
        .build())
    .call();

Use https://eu.api.novu.co/v1/events/trigger api endpoint for the EU region.

curl -L -X POST 'https://api.novu.co/v1/events/trigger' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <SECRET_KEY>' \
--data-raw '{
    "name": "workflow_trigger_identifier",
    "to": [
        {
            "subscriberId": "subscriber_id",
            "email": "email_address"
        }
    ],
    "payload": {
        "attachments": [
            {
                "file": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII",
                "name": "transparent.png",
                "mime": "image/png"
            },
            {
                "file": "iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mNkYPhfz0AEYBxVSF+FAP5FDvcfRYWgAAAAAElFTkSuQmCC",
                "name": "blue.png",
                "mime": "image/png"
            }
        ]
    }
}'

Sending email overrides

You can override the email settings for a single trigger by passing an overrides object. This lets you override the following fields:

bcc
cc
from address
replyTo
replaceToRecipient
senderName
text
to address

import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Required if using EU region
  // serverURL: "https://eu.api.novu.co",
});

await novu.trigger({    
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
  },
  overrides: {
    email: {
      to: ['to@novu.co'],
      from: 'from@novu.co',
      senderName: 'Novu Team',
      text: 'text version of email using overrides',
      replyTo: 'no-reply@novu.co',
      cc: ['1@novu.co'],
      bcc: ['2@novu.co'],
    },
  },
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflowId",
        to={"subscriber_id": "subscriberId"},
        overrides={
            "email": {
                "to": ["to@novu.co"],
                "from": "from@novu.co",
                "senderName": "Novu Team",
                "text": "text version of email using overrides",
                "replyTo": "no-reply@novu.co",
                "cc": ["1@novu.co"],
                "bcc": ["2@novu.co"],
            },
        },
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

_, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflowId",
    To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
        SubscriberID: "subscriberId",
    }),
    Overrides: map[string]map[string]any{
        "email": {
            "to":         []string{"to@novu.co"},
            "from":       "from@novu.co",
            "senderName": "Novu Team",
            "text":       "text version of email using overrides",
            "replyTo":    "no-reply@novu.co",
            "cc":         []string{"1@novu.co"},
            "bcc":        []string{"2@novu.co"},
        },
    },
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity('<NOVU_SECRET_KEY>')
    ->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflowId',
        to: new Components\SubscriberPayloadDto(subscriberId: 'subscriberId'),
        overrides: [
            'email' => [
                'to' => ['to@novu.co'],
                'from' => 'from@novu.co',
                'senderName' => 'Novu Team',
                'text' => 'text version of email using overrides',
                'replyTo' => 'no-reply@novu.co',
                'cc' => ['1@novu.co'],
                'bcc' => ['2@novu.co'],
            ],
        ],
    ),
);

using Novu;
using Novu.Models.Components;
using System.Collections.Generic;

var sdk = new NovuSDK(secretKey: "<NOVU_SECRET_KEY>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflowId",
    To = To.CreateSubscriberPayloadDto(new SubscriberPayloadDto() {
        SubscriberId = "subscriberId",
    }),
    Overrides = new Overrides() {
        Email = new Dictionary<string, object>() {
            { "to", new List<string>() { "to@novu.co" } },
            { "from", "from@novu.co" },
            { "senderName", "Novu Team" },
            { "text", "text version of email using overrides" },
            { "replyTo", "no-reply@novu.co" },
            { "cc", new List<string>() { "1@novu.co" } },
            { "bcc", new List<string>() { "2@novu.co" } },
        },
    },
});

import co.novu.Novu;
import co.novu.models.components.*;
import java.util.List;
import java.util.Map;

Novu novu = Novu.builder()
    .secretKey("<NOVU_SECRET_KEY>")
    .build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflowId")
        .to(To2.of(SubscriberPayloadDto.builder()
            .subscriberId("subscriberId")
            .build()))
        .overrides(TriggerEventRequestDtoOverrides.builder()
            .email(Map.of(
                "to", List.of("to@novu.co"),
                "from", "from@novu.co",
                "senderName", "Novu Team",
                "text", "text version of email using overrides",
                "replyTo", "no-reply@novu.co",
                "cc", List.of("1@novu.co"),
                "bcc", List.of("2@novu.co")))
            .build())
        .build())
    .call();

curl -L -X POST 'https://api.novu.co/v1/events/trigger' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
    "name": "workflowId",
    "to": {
        "subscriberId": "subscriberId"
    },
    "overrides": {
        "email": {
            "to": ["to@novu.co"],
            "from": "from@novu.co",
            "senderName": "Novu Team",
            "text": "text version of email using overrides",
            "replyTo": "no-reply@novu.co",
            "cc": ["1@novu.co"],
            "bcc": ["2@novu.co"]
        }
    }
}'

replaceToRecipient

By default, Novu merges override to addresses with the subscriber email.
Set replaceToRecipient: true to send only to override recipients. The subscriber email is omitted from to. to is replaced with the from address.
When replaceToRecipient is true, include at least one of to, cc, or bcc.

Empty to with cc/bcc (Custom SMTP only)

Setting to: [] with cc or bcc is supported only on Custom SMTP (Nodemailer).
Novu normalizes an empty to to undisclosed-recipients:; so the message sends without exposing addresses in the To field.
Other email providers do not support this pattern.

Targeting a specific provider

By default, Novu uses your primary email provider. However, if you want to bypass this and force a specific, active integration for a trigger, use the integrationIdentifier. This is useful if you have multiple active integrations for different purposes. For example, you might have one integration for transactional emails and one for marketing emails. You can find the integrationIdentifier for each provider in provider page in the Integration Store.

import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Required if using EU region
  // serverURL: "https://eu.api.novu.co",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
  },
  overrides: {
    email: {
      integrationIdentifier: "brevo-abcdef"
    },
  },
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflowId",
        to={"subscriber_id": "subscriberId"},
        overrides={
            "email": {
                "integrationIdentifier": "brevo-abcdef",
            },
        },
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

_, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflowId",
    To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
        SubscriberID: "subscriberId",
    }),
    Overrides: map[string]map[string]any{
        "email": {
            "integrationIdentifier": "brevo-abcdef",
        },
    },
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity('<NOVU_SECRET_KEY>')
    ->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflowId',
        to: new Components\SubscriberPayloadDto(subscriberId: 'subscriberId'),
        overrides: [
            'email' => [
                'integrationIdentifier' => 'brevo-abcdef',
            ],
        ],
    ),
);

using Novu;
using Novu.Models.Components;
using System.Collections.Generic;

var sdk = new NovuSDK(secretKey: "<NOVU_SECRET_KEY>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflowId",
    To = To.CreateSubscriberPayloadDto(new SubscriberPayloadDto() {
        SubscriberId = "subscriberId",
    }),
    Overrides = new Overrides() {
        Email = new Dictionary<string, object>() {
            { "integrationIdentifier", "brevo-abcdef" },
        },
    },
});

import co.novu.Novu;
import co.novu.models.components.*;
import java.util.Map;

Novu novu = Novu.builder()
    .secretKey("<NOVU_SECRET_KEY>")
    .build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflowId")
        .to(To2.of(SubscriberPayloadDto.builder()
            .subscriberId("subscriberId")
            .build()))
        .overrides(TriggerEventRequestDtoOverrides.builder()
            .email(Map.of("integrationIdentifier", "brevo-abcdef"))
            .build())
        .build())
    .call();

curl -L -X POST 'https://api.novu.co/v1/events/trigger' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
    "name": "workflowId",
    "to": {
        "subscriberId": "subscriberId"
    },
    "overrides": {
        "email": {
            "integrationIdentifier": "brevo-abcdef"
        }
    }
}'

Overriding email layout

Each Novu environment can have multiple layouts. Each email step in the workflow can have a layout assigned to it. Overriding the email layout allows you to dynamically override layout settings at trigger time, providing flexible layout management per workflow/channel or per step execution. layoutId values and its behavior:

Value	Behavior
”layout-identifier”	Uses layout with this identifier
”507f1f77bcf86cd799439011”	Uses layout with this MongoDB ObjectId
null	Explicitly no layout - renders email without any layout
undefined	Default behavior - uses step’s configured layout or environment default
Not specified	Same as undefined

Precedence rules:

Step-level override - Highest priority
Workflow-level/channels-level override
Step configuration (configured in workflow editor)
Environment default layout - Lowest priority

import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Required if using EU region
  // serverURL: "https://eu.api.novu.co",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
  },
  payload: {},
  overrides: {
    // Channel-level layouts
    channels: {
	    email: {
		    layoutId: 'black-friday-layout',
	    },
	  },
    steps: {
      'welcome-email': {
        // This email step uses a specific welcome layout
        layoutId: 'welcome-v2'
      },
      'promotional-email': {
        // This email uses the channel-level layout (black-friday-layout)
        // No layoutId specified = inherits from channel level
      },
      'transactional-receipt': {
        // This email explicitly uses no layout (plain email)
        layoutId: null
      }
    }
  }
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflowId",
        to={"subscriber_id": "subscriberId"},
        payload={},
        overrides={
            "channels": {
                "email": {
                    "layoutId": "black-friday-layout",
                },
            },
            "steps": {
                "welcome-email": {
                    "layoutId": "welcome-v2",
                },
                "promotional-email": {},
                "transactional-receipt": {
                    "layoutId": None,
                },
            },
        },
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

_, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflowId",
    To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
        SubscriberID: "subscriberId",
    }),
    Payload: map[string]any{},
    Overrides: map[string]map[string]any{
        "channels": {
            "email": map[string]any{
                "layoutId": "black-friday-layout",
            },
        },
        "steps": map[string]any{
            "welcome-email": map[string]any{
                "layoutId": "welcome-v2",
            },
            "promotional-email": map[string]any{},
            "transactional-receipt": map[string]any{
                "layoutId": nil,
            },
        },
    },
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity('<NOVU_SECRET_KEY>')
    ->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflowId',
        to: new Components\SubscriberPayloadDto(subscriberId: 'subscriberId'),
        payload: [],
        overrides: [
            'channels' => [
                'email' => [
                    'layoutId' => 'black-friday-layout',
                ],
            ],
            'steps' => [
                'welcome-email' => [
                    'layoutId' => 'welcome-v2',
                ],
                'promotional-email' => [],
                'transactional-receipt' => [
                    'layoutId' => null,
                ],
            ],
        ],
    ),
);

using Novu;
using Novu.Models.Components;
using System.Collections.Generic;

var sdk = new NovuSDK(secretKey: "<NOVU_SECRET_KEY>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflowId",
    To = To.CreateSubscriberPayloadDto(new SubscriberPayloadDto() {
        SubscriberId = "subscriberId",
    }),
    Payload = new Dictionary<string, object>(),
    Overrides = new Overrides() {
        Channels = new Channels() {
            Email = new EmailChannelOverrides() {
                LayoutId = "black-friday-layout",
            },
        },
        Steps = new Dictionary<string, StepsOverrides>() {
            { "welcome-email", new StepsOverrides() { LayoutId = "welcome-v2" } },
            { "promotional-email", new StepsOverrides() },
            { "transactional-receipt", new StepsOverrides() { LayoutId = null } },
        },
    },
});

import co.novu.Novu;
import co.novu.models.components.*;
import java.util.Map;

Novu novu = Novu.builder()
    .secretKey("<NOVU_SECRET_KEY>")
    .build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflowId")
        .to(To2.of(SubscriberPayloadDto.builder()
            .subscriberId("subscriberId")
            .build()))
        .payload(Map.of())
        .overrides(TriggerEventRequestDtoOverrides.builder()
            .channels(Channels.builder()
                .email(EmailChannelOverrides.builder()
                    .layoutId("black-friday-layout")
                    .build())
                .build())
            .steps(Map.of(
                "welcome-email", StepsOverrides.builder()
                    .layoutId("welcome-v2")
                    .build(),
                "promotional-email", StepsOverrides.builder().build(),
                "transactional-receipt", StepsOverrides.builder()
                    .layoutId(null)
                    .build()))
            .build())
        .build())
    .call();

curl -L -X POST 'https://api.novu.co/v1/events/trigger' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
    "name": "workflowId",
    "to": {
        "subscriberId": "subscriberId"
    },
    "payload": {},
    "overrides": {
        "channels": {
            "email": {
                "layoutId": "black-friday-layout"
            }
        },
        "steps": {
            "welcome-email": {
                "layoutId": "welcome-v2"
            },
            "promotional-email": {},
            "transactional-receipt": {
                "layoutId": null
            }
        }
    }
}'

Sending provider specific extra fields

You can send provider specific extra fields by passing a _passthrough object in the overrides object. This lets you send extra fields to the provider SDK. Novu internally uses provider’s official SDK to send the email. Each provider has its own supported extra fields. Those extra fields are not validated by Novu and are passed directly to the provider SDK. There are three type of fields that you can send: body, headers, and query. Below is an example of sending tags supported by Resend provider.

import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: "<NOVU_SECRET_KEY>",
  // Required if using EU region
  // serverURL: "https://eu.api.novu.co",
});

await novu.trigger({
  workflowId: "workflowId",
  to: {
    subscriberId: "subscriberId",
  },
  payload: {},
  overrides: {
    providers: {
      resend: {
        _passthrough: {
          body: {
            tags: [
              {
                name: "category",
                value: "confirm_email"
              }
            ] 
          },
          headers: {
            "X-Custom-Header": "custom-header-value"
          },
          query: {
            "queryParam": "queryValue"
          }
        }
      }
    }
  }
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflowId",
        to={"subscriber_id": "subscriberId"},
        payload={},
        overrides={
            "providers": {
                "resend": {
                    "_passthrough": {
                        "body": {
                            "tags": [
                                {
                                    "name": "category",
                                    "value": "confirm_email",
                                },
                            ],
                        },
                        "headers": {
                            "X-Custom-Header": "custom-header-value",
                        },
                        "query": {
                            "queryParam": "queryValue",
                        },
                    },
                },
            },
        },
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

_, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflowId",
    To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
        SubscriberID: "subscriberId",
    }),
    Payload: map[string]any{},
    Overrides: map[string]map[string]any{
        "providers": {
            "resend": map[string]any{
                "_passthrough": map[string]any{
                    "body": map[string]any{
                        "tags": []map[string]any{
                            {
                                "name":  "category",
                                "value": "confirm_email",
                            },
                        },
                    },
                    "headers": map[string]any{
                        "X-Custom-Header": "custom-header-value",
                    },
                    "query": map[string]any{
                        "queryParam": "queryValue",
                    },
                },
            },
        },
    },
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity('<NOVU_SECRET_KEY>')
    ->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflowId',
        to: new Components\SubscriberPayloadDto(subscriberId: 'subscriberId'),
        payload: [],
        overrides: [
            'providers' => [
                'resend' => [
                    '_passthrough' => [
                        'body' => [
                            'tags' => [
                                [
                                    'name' => 'category',
                                    'value' => 'confirm_email',
                                ],
                            ],
                        ],
                        'headers' => [
                            'X-Custom-Header' => 'custom-header-value',
                        ],
                        'query' => [
                            'queryParam' => 'queryValue',
                        ],
                    ],
                ],
            ],
        ],
    ),
);

using Novu;
using Novu.Models.Components;
using System.Collections.Generic;

var sdk = new NovuSDK(secretKey: "<NOVU_SECRET_KEY>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflowId",
    To = To.CreateSubscriberPayloadDto(new SubscriberPayloadDto() {
        SubscriberId = "subscriberId",
    }),
    Payload = new Dictionary<string, object>(),
    Overrides = new Overrides() {
        Providers = new Dictionary<string, Dictionary<string, object>>() {
            { "resend", new Dictionary<string, object>() {
                { "_passthrough", new Dictionary<string, object>() {
                    { "body", new Dictionary<string, object>() {
                        { "tags", new List<Dictionary<string, object>>() {
                            new Dictionary<string, object>() {
                                { "name", "category" },
                                { "value", "confirm_email" },
                            },
                        } },
                    } },
                    { "headers", new Dictionary<string, object>() {
                        { "X-Custom-Header", "custom-header-value" },
                    } },
                    { "query", new Dictionary<string, object>() {
                        { "queryParam", "queryValue" },
                    } },
                } },
            } },
        },
    },
});

import co.novu.Novu;
import co.novu.models.components.*;
import java.util.List;
import java.util.Map;

Novu novu = Novu.builder()
    .secretKey("<NOVU_SECRET_KEY>")
    .build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflowId")
        .to(To2.of(SubscriberPayloadDto.builder()
            .subscriberId("subscriberId")
            .build()))
        .payload(Map.of())
        .overrides(TriggerEventRequestDtoOverrides.builder()
            .providers(Map.of(
                "resend", Map.of(
                    "_passthrough", Map.of(
                        "body", Map.of(
                            "tags", List.of(
                                Map.of(
                                    "name", "category",
                                    "value", "confirm_email"))),
                        "headers", Map.of(
                            "X-Custom-Header", "custom-header-value"),
                        "query", Map.of(
                            "queryParam", "queryValue")))))
            .build())
        .build())
    .call();

curl -L -X POST 'https://api.novu.co/v1/events/trigger' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
    "name": "workflowId",
    "to": {
        "subscriberId": "subscriberId"
    },
    "payload": {},
    "overrides": {
        "providers": {
            "resend": {
                "_passthrough": {
                    "body": {
                        "tags": [
                            {
                                "name": "category",
                                "value": "confirm_email"
                            }
                        ]
                    },
                    "headers": {
                        "X-Custom-Header": "custom-header-value"
                    },
                    "query": {
                        "queryParam": "queryValue"
                    }
                }
            }
        }
    }
}'

Unsubscribe email

By default, Novu does not add any unsubscribe links to the email. Few providers add unsubscribe links to the email by default. If you are looking to add custom unsubscribe links to the email, follow below steps:

Add {{payload.unsubscribeEmail}} field in the email editor.
Build custom unsubscribe link in your application using subscriberId workflowId. Make sure this link is secured with tokens to prevent abuse.
Use Novu preference api to update the email channel preferences for this workflow to false.
Optionally, you can build a custom unsubscribe page and add the link of that page for unsubscribe email option.
Send the value of unsubscribeEmail variable in the payload while triggering the workflow.
Novu will add the unsubscribe link to the email and end user will be able to unsubscribe from the email by clicking on the link.

Receiving email replies

Novu supports inbound email replies — not only sending mail through your email provider. The replyTo override above sets where replies are addressed when sending; to process replies, choose one of these paths:

Goal	Approach
Two-way agent conversation on email	Connect email to an agent via ACI
Forward inbound mail to your backend	Inbound Email with a Webhook route → `email.received`
User replies to a workflow email open an agent thread	Workflow to conversation handoff

SMS replies are not supported in Novu. The SMS channel is outbound-only.

Inbound Email

Verify a domain, add routes, and receive mail on your addresses.

Agents and providers

Connect email to an agent for two-way conversations.

Supported providers

Here are the email providers that are currently supported by Novu. Select any provider to see its detailed setup guide.

SendGrid

Learn how to use the SendGrid provider to send emails using Novu.

Amazon SES

Learn how to use the Amazon SES provider to send emails using Novu.

Postmark

Learn how to use the Postmark provider to send emails using Novu.

Resend

Learn how to use the Resend provider to send emails using Novu.

Brevo

Learn how to use the Brevo provider to send emails using Novu.

Mailgun

Learn how to use the Mailgun provider to send emails using Novu.

Mailjet

Learn how to use the Mailjet provider to send emails using Novu.

Braze

Learn how to use the Braze provider to send emails using Novu.

Infobip

Learn how to use the Infobip provider to send emails using Novu.

MailerSend

Learn how to use the MailerSend provider to send emails using Novu.

Mailtrap

Learn how to use the Mailtrap provider to send emails using Novu.

Mandrill

Learn how to use the Mandrill provider to send emails using Novu.

Maqsam

Learn how to use the Maqsam provider to send emails using Novu.

Netcore

Learn how to use the Netcore provider to send emails using Novu.

Outlook 365

Learn how to use the Outlook 365 provider to send emails using Novu.

Plunk

Learn how to use the Plunk provider to send emails using Novu.

Sparkpost

Learn how to use the Sparkpost provider to send emails using Novu.

Email Webhook

Learn how to use the Email Webhook provider to send emails using Novu.

Custom SMTP

Learn how to use a Custom SMTP provider to send emails using Novu.

​Key features

​How email works in Novu

​Add an email provider

​Add the Email channel to your workflow

​Define the email content

​Store subscriber email addresses

​Trigger the workflow

​Configuring email providers

​Default sender settings

​Provider authentication

​Advanced email features

​Sending attachments

​Sending email overrides

​Targeting a specific provider

​Overriding email layout

​Sending provider specific extra fields

​Unsubscribe email

​Receiving email replies

Inbound Email

Agents and providers

​Supported providers

SendGrid

Amazon SES

Postmark

Resend

Brevo

Mailgun

Mailjet

Braze

Infobip

MailerSend

Mailtrap

Mandrill

Maqsam

Netcore

Outlook 365

Plunk

Sparkpost

Email Webhook

Custom SMTP

Key features

How email works in Novu

Add an email provider

Add the Email channel to your workflow

Define the email content

Store subscriber email addresses

Trigger the workflow

Configuring email providers

Default sender settings

Provider authentication

Advanced email features

Sending attachments

Sending email overrides

Targeting a specific provider

Overriding email layout

Sending provider specific extra fields

Unsubscribe email

Receiving email replies

Supported providers