SendGrid

SendGrid

Typed Twilio SendGrid v3 API client for Deno, Bun, Node.js and Cloudflare Workers. Send transactional email, inspect API-key scopes, and verify ECDSA-signed Event Webhook requests. A lightweight alternative to @sendgrid/mail for the endpoints it covers.

Overview

SendGrid sends transactional email via POST /mail/send and lists the permission scopes granted to an API key via GET /scopes. It uses RESTler for transport and Guardian for runtime request/response validation — the mail-send request body (personalizations, attachments, mail settings, tracking settings, …) is validated before it's ever sent.

Testing your code

Your tests don't need to fake HTTP. Have your code take a SendGrid instance and pass in a stand-in that returns the shapes from @tundraconnect/sendgrid/schemas or throws a real SendGridError:

import { SendGridError } from '@tundraconnect/sendgrid/errors';

const outage = new SendGridError('SERVICE_UNAVAILABLE', { status: 503 });
console.log(outage.code);

To exercise the client itself against a fake transport, subclass it and reassign the protected _fetch.

Documentation

Topic	Description
API	Client configuration and endpoint methods
Errors	Error codes and diagnostic metadata
Schemas	Public Guardian schemas and inferred types

Upstream

• Twilio SendGrid API reference
• Create a Twilio SendGrid account

Installation

Deno:

deno add jsr:@tundraconnect/sendgrid

Bun:

bunx jsr add @tundraconnect/sendgrid

Node.js:

npx jsr add @tundraconnect/sendgrid

Quick Start

import { SendGrid } from '@tundraconnect/sendgrid';

const client = new SendGrid({
  auth: { type: 'BEARER', token: 'SG.xxxxx', prefix: 'Bearer' },
});

const { messageId } = await client.sendMail({
  personalizations: [{ to: [{ email: 'dest@example.com' }] }],
  from: { email: 'sender@example.com' },
  subject: 'Hello from SendGrid',
  content: [{ type: 'text/plain', value: 'Hi there!' }],
});

console.log(messageId);

Webhooks

import { SendGrid } from '@tundraconnect/sendgrid';

const client = new SendGrid({
  auth: { type: 'BEARER', token: 'SG.xxxxx', prefix: 'Bearer' },
});

export async function onEventWebhook(req: Request): Promise<void> {
  const raw = await req.text(); // text(), never json()
  const events = await client.verifyWebhook({
    payload: raw,
    headers: req.headers,
    publicKey: 'your-verification-key',
  });
  // `events` is now trustworthy.
}

See API → Webhooks.

License

MIT. Part of Tundra Connect, typed vendor API clients for Deno, Bun, Node.js and Cloudflare Workers.