E-mail Providers Integration

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.

How email works in Novu

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

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.

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',
      }
    ],
  },
});

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
• 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: ['[email protected]'],
      from: '[email protected]',
      senderName: 'Novu Team',
      text: 'text version of email using overrides',
      replyTo: '[email protected]',
      cc: ['[email protected]'],
      bcc: ['[email protected]'],
    },
  },
});

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"
    },
  },
});

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:

Precedence rules:

1. Step-level override - Highest priority
2. Workflow-level/channels-level override
3. Step configuration (configured in workflow editor)
4. 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
      }
    }
  }
});

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"
          }
        }
      }
    }
  }
});

Supported providers

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