ContextQMD
Back to Novu

SendGrid Email Integration with Novu

docs/platform/integrations/email/sendgrid.mdx

3.18.012.4 KB
Original Source

You can use the SendGrid provider to send transactional emails to your customers using the Novu Platform with a single API to create multi-channel experiences.

Getting Started

To use the Sendgrid provider in the email channel, you will need to create a Sendgrid account and add your API key to the SendGrid integration on the Novu platform.

Generating an API Key

To generate a new API key in SendGrid, follow these steps:

  • Log in to your SendGrid account.
  • Click on the Settings gear icon in the top right corner of the screen, and then click "API Keys" from the drop-down menu.
  • On the API Keys page, click the Create API Key button.
  • Give the API key a name and select the following permissions
  • Mail Send - Full Access
  • (Optional) Template Engine - Read Only
  • Click the Create & View button to generate the API key. The key will be displayed on the screen, but you will only be able to view it once, so make sure to save it in a safe place.

NOTE

The access level of the key will determine what actions the API Key can take, so please choose the correct one.

  • Mail Send - Full Access
  • (Optional) Template Engine - Read Only

Authenticating your Sender Identity

Before you can send emails on a large scale, you will need to authenticate your Sender Identity. This is due to the latest regulatory changes regarding SPAM rules and email fraud. Most of the providers including Sendgrid require you to authenticate your Sender Identity before you can send emails.

SendGrid allows you to authenticate your sender identity using one of the following methods:

SendGrid integration with Novu

  • Visit the Integrations store on the Novu web dashboard.
  • Click on Add a Provider.
  • Select SendGrid service.
  • Enter your SendGrid API Key.
  • Fill in the From email address field using the authenticated email from the previous step.
  • Click on the Disabled button and mark it as Active.
  • Click on the Update button.
  • You should now be able to send notifications through SendGrid using Novu.

Using SendGrid template

Novu has its own email editor for writing email template. To send pre-made template in SendGrid, providers overrides can be used to send template details. Make sure sendgrid Api Key has enough permission to read and process the template.

<Note> Sending `customData` field in overrides to send sendgrid template will work only in following cases: - if workflow is triggered to only one subscriber - if workflow is triggered to multiple subscribers or topic but sendgrid template does not have any dynamic variables related to subscriber attributes like `firstName`, `lastName`, `email`, etc as same overrides will be applied to all subscribers. </Note> <Tabs> <Tab title="Node.js"> ```typescript import { Novu } from '@novu/api';

const novu = new Novu({ secretKey: "<NOVU_SECRET_KEY>" });

await novu.trigger({ workflowId: "workflowId", to: { subscriberId: "subscriberId", }, payload: {}, overrides: { "providers": { "sendgrid": { "templateId": "d-d965b02b1b5d4856bf332a5e98c7470c", "dynamicTemplateData": { "total": "$ 239.85", "receipt": true, "name": "Sample Name", "address01": "1234 Fake St.", "address02": "Apt. 123", "city": "Place", "state": "CO", "zip": "80202" } } } }, });

  </Tab>
  <Tab title="Python">
```python
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": {
                "sendgrid": {
                        "templateId": "d-d965b02b1b5d4856bf332a5e98c7470c",
                        "dynamicTemplateData": {
                                "total": "$ 239.85",
                                "receipt": true,
                                "name": "Sample Name",
                                "address01": "1234 Fake St.",
                                "address02": "Apt. 123",
                                "city": "Place",
                                "state": "CO",
                                "zip": "80202"
                        }
                }
        }
},
    ))
</Tab> <Tab title="Go"> ```go 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")))

res, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{ WorkflowID: "workflowId", To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{ SubscriberID: "subscriberId", }), Payload: map[string]any{}, Overrides: map[string]any{ "providers": { "sendgrid": { "templateId": "d-d965b02b1b5d4856bf332a5e98c7470c", "dynamicTemplateData": { "total": "$ 239.85", "receipt": true, "name": "Sample Name", "address01": "1234 Fake St.", "address02": "Apt. 123", "city": "Place", "state": "CO", "zip": "80202" } } } }, }, nil)

  </Tab>
  <Tab title="PHP">
```php
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": {
                "sendgrid": {
                        "templateId": "d-d965b02b1b5d4856bf332a5e98c7470c",
                        "dynamicTemplateData": {
                                "total": "$ 239.85",
                                "receipt": true,
                                "name": "Sample Name",
                                "address01": "1234 Fake St.",
                                "address02": "Apt. 123",
                                "city": "Place",
                                "state": "CO",
                                "zip": "80202"
                        }
                }
        }
},
    ),
);
</Tab> <Tab title=".NET"> ```csharp using Novu; using Novu.Models.Components;

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

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() { WorkflowId = "workflowId", To = To.CreateSubscriberPayloadDto(new SubscriberPayloadDto() { SubscriberId = "subscriberId" }), Payload = {}, Overrides = { "providers": { "sendgrid": { "templateId": "d-d965b02b1b5d4856bf332a5e98c7470c", "dynamicTemplateData": { "total": "$ 239.85", "receipt": true, "name": "Sample Name", "address01": "1234 Fake St.", "address02": "Apt. 123", "city": "Place", "state": "CO", "zip": "80202" } } } }, });

  </Tab>
  <Tab title="Java">
```java
import co.novu.Novu;
import co.novu.models.components.*;

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({})
        .overrides({
        "providers": {
                "sendgrid": {
                        "templateId": "d-d965b02b1b5d4856bf332a5e98c7470c",
                        "dynamicTemplateData": {
                                "total": "$ 239.85",
                                "receipt": true,
                                "name": "Sample Name",
                                "address01": "1234 Fake St.",
                                "address02": "Apt. 123",
                                "city": "Place",
                                "state": "CO",
                                "zip": "80202"
                        }
                }
        }
})
        .build())
    .call();
</Tab> <Tab title="cURL"> ```bash curl --location 'https://api.novu.co/v1/events/trigger' \ --header 'Content-Type: application/json' \ --header 'Authorization: ApiKey <NOVU_SECRET_KEY>' \ -d '{ "name": "workflowId", "to": [ "subscriberId" ], "payload": {}, "overrides": { "providers": { "sendgrid": { "templateId": "d-d965b02b1b5d4856bf332a5e98c7470c", "dynamicTemplateData": { "total": "$ 239.85", "receipt": true, "name": "Sample Name", "address01": "1234 Fake St.", "address02": "Apt. 123", "city": "Place", "state": "CO", "zip": "80202" } } } } }' ``` </Tab> <Tab title="Novu Framework"> ```typescript import { workflow } from "@novu/framework"; import { z } from "zod";

export const sendgridOverridesEmailExample = workflow( "sendgrid-email-overrides", async ({ step, payload }) => { await step.email( "sendgrid-email-overrides", async () => { return { subject: "SendGrid Overrides Example", body: "This body content should be overridden by the SendGrid template", }; }, { providers: { sendgrid: ({}) => ({ _passthrough: { body: { templateId: payload.dynamicTemplateId, dynamicTemplateData: { // Example variables to be used in the template total: "$ 239.85", items: [ { text: payload.itemName, image: "https://marketing-image-production.s3.amazonaws.com/uploads/8dda1131320a6d978b515cc04ed479df259a458d5d45d58b6b381cae0bf9588113e80ef912f69e8c4cc1ef1a0297e8eefdb7b270064cc046b79a44e21b811802.png", price: "$ 79.95", }, { text: "Old Line Sneakers rlfjrjrh4hr4rh4", image: "https://marketing-image-production.s3.amazonaws.com/uploads/3629f54390ead663d4eb7c53702e492de63299d7c5f7239efdc693b09b9b28c82c924225dcd8dcb65732d5ca7b7b753c5f17e056405bbd4596e4e63a96ae5018.png", price: "$ 79.95", }, ], receipt: true, name: "Sample Name", address01: "1234 Fake St.", address02: "Apt. 123", city: "Place", state: "CO", zip: "80202", }, }, }, }), }, } ); }, { payloadSchema: z.object({ itemName: z.string().default("New Line Sneakers"), dynamicTemplateId: z .string() .default("d-d965b02b1b5d4856bf332a5e98c7470c"), }), } );

  </Tab>
</Tabs>

## Next Steps

<Columns cols={2}>
  <Card title="Configure bcc, cc, and reply-to" href="/platform/integrations/email#sending-email-overrides">
    Learn how to configure bcc, cc, and reply-to for your email notifications using email overrides
  </Card>
  <Card title="Sending email attachments" href="/platform/integrations/email#sending-email-attachments">
    Learn how to send attachments with email notifications
  </Card>
  <Card title="Use different email integration" href="/platform/integrations/email#sending-email-overrides">
    Learn how to use different email provider integrations to be used to send emails
  </Card>
</Columns>