@keystrokehq/sendgrid

Official Keystroke integration for SendGrid (Twilio) — transactional + marketing email, templates, contacts, lists, segments, suppressions, deliverability, and webhook helpers.

This package follows the canonical Keystroke integration shape with four public subpaths.

Install

pnpm add @keystrokehq/sendgrid

Package exports

Import from the canonical barrel subpaths:

• @keystrokehq/sendgrid — credential sets, operations, and schemas
• @keystrokehq/sendgrid/credential-sets — sendgridCredentialSet and SendGridCredentials
• @keystrokehq/sendgrid/operations — all 152 SendGrid operations (+ *Tool aliases)
• @keystrokehq/sendgrid/schemas — shared Zod schemas and inferred types

Connect

SendGrid authenticates with a single API key. Create one in the SendGrid console (Settings → API Keys) — we recommend a Restricted Access key with only the scopes your workflows need.

import {
  sendgridCredentialSet,
  type SendGridCredentials,
} from '@keystrokehq/sendgrid/credential-sets';

const credentials: SendGridCredentials = {
  SENDGRID_API_KEY: 'SG.xxx...',
  // Optional:
  SENDGRID_SUBUSER: 'acme-eu',          // adds `on-behalf-of: acme-eu` header
  SENDGRID_ACCOUNT_REGION: 'eu',        // default: 'global'
  SENDGRID_EVENT_WEBHOOK_PUBLIC_KEY: '-----BEGIN PUBLIC KEY-----\n…\n-----END PUBLIC KEY-----',
  SENDGRID_INBOUND_PARSE_TOKEN: 'token-abc',
};

void credentials;
void sendgridCredentialSet;

Fields

Quickstart

import { sendEmailOperation } from '@keystrokehq/sendgrid/operations';

void sendEmailOperation;

Operations (152)

Phase-1 coverage spans Mail Send, Templates, Marketing Contacts/Lists/Segments/Single Sends/Custom Fields, Suppressions, Senders, Stats, Email Validation, User Account, Alerts, API Keys, Authenticated Domains, and Event + Inbound Parse webhook configuration. Every operation id is prefixed with sendgrid. — for example sendgrid.send-email, sendgrid.upsert-contacts, and sendgrid.create-event-webhook.

Utility helpers for HTTP, EU/global routing, and webhook verification live under src/utils/ and are consumed internally by operations; import operations and schemas from the public subpaths above.

Sending email

import { sendEmailOperation } from '@keystrokehq/sendgrid/operations';

void sendEmailOperation;

The Mail Send operation accepts the full v3 body: multiple personalizations, dynamic template substitution, attachments, categories, customArgs, sandbox mode, and sendAt for scheduled sends. Pass a batchId to later cancel or pause messages.

Marketing: contacts, lists, segments, single sends

import {
  createListOperation,
  createSegmentOperation,
  createSingleSendOperation,
  scheduleSingleSendOperation,
  upsertContactsOperation,
} from '@keystrokehq/sendgrid/operations';

void upsertContactsOperation;
void createListOperation;
void createSegmentOperation;
void createSingleSendOperation;
void scheduleSingleSendOperation;

Suppressions

import {
  addGlobalSuppressionsOperation,
  createSuppressionGroupOperation,
  deleteSpamReportOperation,
  listBouncesOperation,
} from '@keystrokehq/sendgrid/operations';

void addGlobalSuppressionsOperation;
void createSuppressionGroupOperation;
void listBouncesOperation;
void deleteSpamReportOperation;

Webhooks

Event Webhook (signed, Ed25519)

import {
  createEventWebhookOperation,
  getSignedPublicKeyOperation,
  toggleWebhookSignatureOperation,
} from '@keystrokehq/sendgrid/operations';

void createEventWebhookOperation;
void getSignedPublicKeyOperation;
void toggleWebhookSignatureOperation;

IMPORTANT: SendGrid signs the concatenation of the X-Twilio-Email-Event-Webhook-Timestamp header value and the raw request body bytes. Your HTTP surface must preserve the raw body — do not JSON-reparse and re-serialize before verifying.

Inbound Parse

import { createParseSettingOperation } from '@keystrokehq/sendgrid/operations';

void createParseSettingOperation;

SendGrid does not sign Inbound Parse payloads. Verification uses a Keystroke-minted token embedded in the receiver URL (plus an optional IP allowlist). Rotate the token periodically.

Caveats

• No OAuth. SendGrid v3 only supports API-key auth.

• Apple Mail Privacy Protection. open events now carry sg_machine_open: true when the open is an Apple MPP cache-fetch. Filter on this flag or your workflows will trigger on every Apple Mail user.

• One-click unsubscribe (RFC 8058). Required by major inbox providers for bulk senders. Set List-Unsubscribe-Post: List-Unsubscribe=One-Click in your headers on sendEmail.

• Apple MPP + bounce classification. bounce events include bounce_classification — use it to distinguish reputation damage from mailbox-full soft bounces.

• Plan-gated endpoints. stats.getEngagementQualityScores requires Pro+. /messages (Email Activity add-on) and reseller endpoints also 402/403 on most tenants. The client surfaces these as SendGridError with kind: 'forbidden' / 'auth'.

• Region split. An API key scoped to global cannot act on eu data and vice versa. Set SENDGRID_ACCOUNT_REGION correctly at connect time.

• Legacy /contactdb/*, Legacy Marketing Campaigns, Designs API, Reverse DNS, IP pools, Subusers, Teammates, SSO, Mail/Tracking Settings. Not wrapped in phase 1.

• Phase 1 coverage. This package ships 152 operations focused on Mail Send, Templates, Marketing Contacts/Lists/Segments/Single Sends/CustomFields, Suppressions, Senders, Stats, Email Validation, User Account, Alerts, API Keys, Authenticated Domains, and the Event + Inbound Parse webhook config surface.

Verification helpers

Event Webhook and Inbound Parse verification helpers live in src/utils/verification.ts and are used internally by the platform webhook surfaces. They are not part of the four public package exports.

License

MIT © Keystroke