EmailProvidersSendGrid

SendGrid

Send emails using the SendGrid API with @visulima/email

SendGrid Provider

The SendGrid provider allows you to send emails through the SendGrid Mail Send API, a cloud-based email service for transactional and marketing emails.

Runtime Support: Universal (Node.js, Deno, Bun, Cloudflare Workers)

Setup

import { createMail } from "@visulima/email";
import { sendGridProvider } from "@visulima/email/providers/sendgrid";

const mail = createMail(
    sendGridProvider({
        apiKey: process.env.SENDGRID_API_KEY!,
    }),
);

Configuration

The SendGridConfig interface extends BaseConfig with the following options:

OptionTypeRequiredDefaultDescription
apiKeystringYes-Your SendGrid API key
endpointstringNohttps://api.sendgrid.comCustom API endpoint
debugbooleanNofalseEnable debug logging
loggerConsoleNo-Custom logger instance
retriesnumberNo3Number of retry attempts
timeoutnumberNo30000Request timeout in milliseconds

Basic Usage

import { MailMessage } from "@visulima/email";

const message = new MailMessage()
    .to("user@example.com")
    .from("sender@example.com")
    .subject("Hello from SendGrid")
    .html("<h1>Hello World</h1>");

const result = await mail.send(message);

Provider-Specific Email Options

The SendGrid provider supports extensive additional options through SendGridEmailOptions:

Dynamic Templates

import type { SendGridEmailOptions } from "@visulima/email/providers/sendgrid";

const options: SendGridEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "",
    templateId: "d-xxx",
    templateData: { name: "John", company: "Acme" },
};

Tracking Settings

const options: SendGridEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "<h1>Hello</h1>",
    trackingSettings: {
        clickTracking: { enable: true, enableText: false },
        openTracking: { enable: true, substitutionTag: "%open%" },
        subscriptionTracking: {
            enable: true,
            text: "Unsubscribe here: <% %>",
            html: "<a href='<% %>'>Unsubscribe</a>",
            substitutionTag: "<% %>",
        },
        ganalytics: {
            enable: true,
            utmSource: "email",
            utmMedium: "transactional",
            utmCampaign: "welcome",
        },
    },
};

Mail Settings

const options: SendGridEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "<h1>Hello</h1>",
    mailSettings: {
        sandboxMode: true,
        bypassListManagement: false,
        footer: {
            enable: true,
            text: "Footer text",
            html: "<p>Footer HTML</p>",
        },
    },
};
OptionTypeDescription
templateIdstringSendGrid dynamic template ID
templateDataRecord<string, unknown>Dynamic template data
sendAtnumberSend at (Unix timestamp)
batchIdstringBatch ID for batch sending
asmGroupIdnumberAdvanced Suppression Management group ID
ipPoolNamestringIP pool name
mailSettingsobjectMail settings (sandbox, footer, etc.)
trackingSettingsobjectTracking settings (clicks, opens, analytics)

Supported Features

FeatureSupported
AttachmentsYes
Batch SendingYes
Custom HeadersYes
HTMLYes
Reply-ToYes
SchedulingYes
TaggingYes
TemplatesYes
TrackingYes
Support

Contribute to our work and keep us going

Community is the heart of open source. The success of our packages wouldn't be possible without the incredible contributions of users, testers, and developers who collaborate with us every day.Want to get involved? Here are some tips on how you can make a meaningful impact on our open source projects.

Ready to help us out?

Be sure to check out the package's contribution guidelines first. They'll walk you through the process on how to properly submit an issue or pull request to our repositories.

Submit a pull request

Found something to improve? Fork the repo, make your changes, and open a PR. We review every contribution and provide feedback to help you get merged.

Good first issues

Simple issues suited for people new to open source development, and often a good place to start working on a package.
View good first issues