Channels providers integration

content/docs/platform/integrations/email/index.mdx

@@ -4,78 +4,97 @@ title: 'E-mail'
 description: 'Learn how to configure the Email channel'
 ---
 
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import { Step, Steps } from 'fumadocs-ui/components/steps';
 
-The Email Channel is a critical component for delivering notifications reliably. Whether it's a password reset, an onboarding email, or an alert about account activity, email remains a trusted medium for reaching users.
-Novu simplifies this process, allowing you to focus on implementation rather than infrastructure.
+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.
 
-## Key Features
+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.
 
-- **Multi-Provider Support**: Integrate any major provider like SendGrid, SES, or Mailgun
-- **Failover Mechanisms**: Automatically retry with a backup provider to ensure reliability
-- **Customizable Templates**: Leverage templates with dynamic placeholders to personalize messages
-- **Delivery Insights (Coming Soon)**: Track delivery status, open rates, and more in the Novu dashboard
+## Key features
 
-## Common Use Cases
+- **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.
 
-- **Transactional Emails**: Password resets, account verification, purchase confirmations
-- **System Alerts**: Security notifications, system updates
-- **Engagement Emails**: Onboarding, reminders, promotional updates
+## How email works in Novu
 
-Novu can be used to deliver email messages to your subscribers using a unified delivery API. You can easily integrate your favorite email provider using the built-in integration store.
+Here’s the typical flow for sending an email notification through Novu:
+
+<Steps> 
+<Step> 
+
+### 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](/platform/integrations/email#supported-providers).
+
+</Step>
+<Step> 
+### 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.
+</Step>
+<Step> 
+### 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.
+</Step>
+<Step> 
+### 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.
+</Step>
+<Step>
+### Trigger the workflow
+
+[Trigger the workflow](/api-reference/events/trigger-event) from your application code by sending an event to Novu. Novu automatically:
+1. Resolves the subscriber.
+2. Selects the correct provider.
+3. Renders the email template. 
+4. Delivers the message through the configured email integration.
+</Step>
+</Steps>
+
+<Callout type="info">Learn how to [build email template](/platform/workflow/template-editor) using the block editor, custom HTML, and dynamic variables.</Callout>
 
 ## Configuring email providers
 
-When creating an email provider integration you will be asked to provide additional fields alongside the provider-specific credentials:
+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.
 
-- **Sender name** - Will be displayed as the sender of the message
-- **From email address** - Emails sent using Novu will be sent using this address
+### Default sender settings
 
-For some email providers including SendGrid you will have to authenticate the **From email address** to make sure you will send email messages using an authorized address.
+Novu asks for two default settings for any email provider you connect:
 
-## Sending Email Overrides
+- **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.
 
-The overrides field supports an email property. The email overrides field have properties like `to`, `from`, `senderName` etc
+These are the default values used for every email sent via this integration. You can override them when triggering a workflow if needed.
 
-<Tabs items={['Node.js']}>
-<Tab value="Node.js">
-```javascript
-import { Novu } from '@novu/api';
+### Provider authentication
 
-const novu = new Novu({
-  secretKey: "<NOVU_SECRET_KEY>",
-  // Use serverURL for EU region
-  // serverURL: "https://eu.api.novu.co",
-});
+You must provide credentials specific to your email provider for a successful integration.
 
-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]'],
-    },
-  },
-});
-```
-</Tab>
-</Tabs>
+<Callout type="info">For detailed setup guides for each integration, refer to the [Supported Providers](/platform/integrations/email#supported-providers) list at the bottom of this page.</Callout>
 
-<Callout type="info">
-It's very important to know that Novu merges the `to` field in the email overrides with the subscriber email. It DOES NOT REPLACE IT.
-</Callout>
+### Setting up failover
 
-## Sending Email attachments
+Novu ensures high deliverability with an automatic failover system. You can have multiple active email providers in the same environment.
 
-You can easily send attachments with the Novu API by passing the attachments array when triggering an Email based workflow. Attachment file can either be in the `buffer` or `base64` format. There is total limit of 20 mb for all attachments included and email size.
+- **Primary integration**: You must designate one of your active providers as the primary provider. Novu always attempts to send the email using this provider first.
+- **Failover logic**: If the primary provider fails to send the notification, then Novu automatically attempts to send the email through one of your other active providers.
+
+This built-in redundancy means you don't have to manage provider downtime yourself.
+
+## 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.
 
 <Tabs items={['Node.js', 'cURL']}>
 <Tab value="Node.js">
@@ -93,7 +112,7 @@ await novu.trigger({
   to: {
     subscriberId: "subscriberId",
   },
-  payload: {
+  payload: { // [!code ++:16]
     attachments: [
       {
         // buffer format
@@ -147,18 +166,56 @@ curl -L -X POST 'https://api.novu.co/v1/events/trigger' \
 </Tab>
 </Tabs>
 
-## Using different email integration
+### Sending email overrides
 
-In Novu integration store, multiple email channel type provider integrations can be active at the same time. But only one provider integration can be primary at a time. This primary integration will be used as a provider to deliver the email by default. If you want to use a different active provider integration then you can use the `integrationIdentifier` email overrides field.
+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
 
-If there are 4 active email integrations with these identifiers:
+<Tabs items={['Node.js']}>
+<Tab value="Node.js">
+```javascript
+import { Novu } from '@novu/api';
 
-1. sendgrid-abcdef
-2. sendgrid-ghijkl
-3. brevo-abcdef
-4. mailersend-abcdef
+const novu = new Novu({
+  secretKey: "<NOVU_SECRET_KEY>",
+  // Use serverURL for EU region
+  // serverURL: "https://eu.api.novu.co",
+});
 
-Here, if `sendgrid-abcdef` is primary integration and you want to use `brevo-abcdef` with this trigger then you can use `integrationIdentifier` email overrides field as below:
+await novu.trigger({    
+  workflowId: "workflowId",
+  to: {
+    subscriberId: "subscriberId",
+  },
+  overrides: { // [!code ++:11]
+    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]'],
+    },
+  },
+});
+```
+</Tab>
+</Tabs>
+
+<Callout type="info">Note that Novu merges the `to` field in the email overrides with the subscriber email. It does _not_ replace it.</Callout>
+
+### 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**.
 
 <Tabs items={['Node.js']}>
 <Tab value="Node.js">
@@ -178,18 +235,36 @@ await novu.trigger({
   },
   overrides: {
     email: {
-      integrationIdentifier: "brevo-abcdef"
+      integrationIdentifier: "brevo-abcdef" // [!code ++]
     },
   },
 });
 ```
 </Tab>
 </Tabs>
 
-<Callout type="info">
-Integration identifier is similar to Provider identifier but it is different than Provider Id. It is unique for each integration. You can find the `integrationIdentifier` in the integration store page.
-</Callout>
-
-<Callout type="info">
-Looking to integrate an email provider? Check out our [provider integrations](/platform/integrations/email).
-</Callout>
+## Supported providers
+
+Here are the email providers that are currently supported by Novu. Select any provider to see its detailed setup guide.
+
+<Cards>
+  <Card title="SendGrid" href="/platform/integrations/email/sendgrid"> Learn how to use the SendGrid provider to send emails using Novu.</Card> 
+  <Card title="Amazon SES" href="/platform/integrations/email/amazon-ses"> Learn how to use the Amazon SES provider to send emails using Novu.</Card> 
+  <Card title="Postmark" href="/platform/integrations/email/postmark"> Learn how to use the Postmark provider to send emails using Novu.</Card>
+  <Card title="Resend" href="/platform/integrations/email/resend"> Learn how to use the Resend provider to send emails using Novu.</Card> 
+  <Card title="Brevo" href="/platform/integrations/email/brevo"> Learn how to use the Brevo provider to send emails using Novu.</Card>
+  <Card title="Mailgun" href="/platform/integrations/email/mailgun"> Learn how to use the Mailgun provider to send emails using Novu.</Card>
+  <Card title="Mailjet" href="/platform/integrations/email/mailjet"> Learn how to use the Mailjet provider to send emails using Novu.</Card>
+  <Card title="Braze" href="/platform/integrations/email/braze"> Learn how to use the Braze provider to send emails using Novu.</Card> 
+  <Card title="Infobip" href="/platform/integrations/email/infobip"> Learn how to use the Infobip provider to send emails using Novu.</Card> 
+  <Card title="MailerSend" href="/platform/integrations/email/mailersend"> Learn how to use the MailerSend provider to send emails using Novu.</Card>
+  <Card title="Mailtrap" href="/platform/integrations/email/mailtrap"> Learn how to use the Mailtrap provider to send emails using Novu.</Card>
+  <Card title="Mandrill" href="/platform/integrations/email/mandrill"> Learn how to use the Mandrill provider to send emails using Novu.</Card> 
+  <Card title="Maqsam" href="/platform/integrations/email/maqsam"> Learn how to use the Maqsam provider to send emails using Novu.</Card> 
+  <Card title="Netcore" href="/platform/integrations/email/netcore"> Learn how to use the Netcore provider to send emails using Novu.</Card>
+  <Card title="Outlook 365" href="/platform/integrations/email/outlook-365"> Learn how to use the Outlook 365 provider to send emails using Novu.</Card> 
+  <Card title="Plunk" href="/platform/integrations/email/plunk"> Learn how to use the Plunk provider to send emails using Novu.</Card>
+  <Card title="Sparkpost" href="/platform/integrations/email/sparkpost"> Learn how to use the Sparkpost provider to send emails using Novu.</Card>
+  <Card title="Email Webhook" href="/platform/integrations/email/email-webhook"> Learn how to use the Email Webhook provider to send emails using Novu.</Card>
+  <Card title="Custom SMTP" href="/platform/integrations/email/custom-smtp"> Learn how to use a Custom SMTP provider to send emails using Novu.</Card>
+</Cards>

content/docs/platform/integrations/email/meta.json

@@ -1,4 +1,4 @@
 {
   "icon": "Mail",
-  "pages": ["adding-email", "writing-email-template", "...", "activity-tracking"]
+  "pages": ["(providers)", "activity-tracking"]
 }

content/docs/platform/integrations/overview.mdx

@@ -1,22 +1,67 @@
 ---
 pageTitle: 'Novu Integration Hub'
 title: 'Overview'
-description: 'Discover how to integrate Novu with your tech stack including delivery providers, content frameworks, and validation libraries.'
+description: 'Learn about the providers that Novu supports for Email, Push, SMS and Chant channels, and how to integrate them to send notifications and receive events.'
 icon: 'LayoutDashboard'
 ---
 
-import { Card, Cards } from 'fumadocs-ui/components/card';
+Providers are the third-party services that deliver your notifications through the various channels. These are services such as SendGrid for email, Twilio for SMS, or Slack for chat.
 
-Novu was designed to be integrated with any part of your tech stack. This includes:
+Novu provides a unified integration layer that connects your application to all these different providers. You connect your provider accounts to Novu from the Integration Store on the Novu dashboard, and Novu's API handles the rest.
 
-- Delivery providers
-- Content frameworks
-- Validation and schema libraries
-- and more!
+This approach means you can add, remove, or switch providers at any time without having to change your application's code. It also allows Novu to manage complex logic like provider fallbacks, for example, "If SendGrid fails, try sending with Amazon SES".
 
-## Delivery provider integrations
+## Provider vs. Integration
 
-You can find the list of available integrations for each channel:
+Understanding the difference between a provider and an integration is key to managing your channels.
+
+- **Provider**: A provider is the third-party service responsible for sending the actual notification such as, Twilio, SendGrid, or Slack. Every provider supported by Novu is identified by a providerId. Refer to this resource to see the full list of provider IDs used in Novu.
+
+- **Integration**: An integration is your specific, configured instance of that provider. It's the provider plus your unique credentials and settings. When creating an integration, you are required to assign it a name and identifier. 
+
+  While the name can be changged, the identifier cannot be changed after creation. This identifier is called the `integrationIdentifier`.
+
+![integrationIdentifier](/images/channels-and-providers/integrationidentifier.png)
+
+This means that you can have provider but two separate integrations for that particular provider. Each of these is a unique integration that you can manage and trigger independently.
+
+<Callout type="info">Novu providers demo integrations. To learn more about how to use them for testing, see the [Demo Integration](/platform/integrations/demo-providers) guide.</Callout>
+
+### Primary vs. Active integrations
+
+Each environment can have multiple active integrations for a single channel.
+
+![Primary and active integration](/images/channels-and-providers/primary-active-integrations.png)
+
+- **Active integration**: Any integration that is "on" and ready to send notifications. You can disable an active integration at any time to stop sending messages through it.
+- **Primary integration**: This is the default integration used when you trigger a notification.
+
+How the primary integration behaves depends on the channel:
+
+- **Email and SMS channels**: You can have many active integrations, but only one can be marked as the primary at a time. This primary integration is used by default for all email or SMS notifications unless you specifically override it.
+
+- **Push and chat channels**: These channels do not use a single primary integration. Instead, Novu uses all active integrations in parallel to deliver the message.
+
+If you disable an integration that is currently marked as "primary" for Email or SMS channels, then Novu automatically promotes another active integration to be the new primary. You can also manually set which active integration you want to be the primary one from the Integration Store.
+
+## Managing integrations across environments
+
+Each integration is scoped to a specific [environment](/platform/concepts/environments). This means you must configure separate integrations for each environment, even if they point to the same provider.
+
+This separation ensures that test messages don’t accidentally go to production users, and different credentials or delivery settings can be safely isolated across environments.
+
+## Override default settings
+
+Novu provides an `overrides` object that can be used to access features that Novu doesn't currently support but are supported by certain providers. This feature includes: 
+- Setting custom SendGrid headers.
+- Using Slack blocks. 
+- Defining platform-specific sounds for FCM push notifications.
+
+<Callout>For a complete guide on Overrides, refer to the [Trigger Overrides](/platform/integrations/trigger-overrides) documentation.</Callout>
+
+## Integration guides
+
+Select a channel below to find the list of all supported providers integrations and their detailed setup guides:
 
 <Cards>
   <Card title="Email" href="/platform/integrations/email">