SendGrid Toolkit

SDK, CLI, and MCP server for SendGrid deliverability across many accounts.

Companies that run one SendGrid account per brand end up with a support team logging into four dashboards to answer "why isn't this customer getting our email?". This toolkit fans every operation out across all configured accounts in parallel and returns one report, so the answer is a single CLI command or a single MCP tool call.

sendgrid diagnose someone@example.com          # investigate everywhere
sendgrid clear someone@example.com --all-accounts --dry-run   # preview the fix
sendgrid clear someone@example.com --all-accounts             # apply it

Install the CLI

Standalone binary (recommended)

curl -fsSL https://raw.githubusercontent.com/spenserhale/sendgrid-ai-toolkit/main/scripts/install.sh | sh

Detects OS and architecture, downloads the matching binary from the latest release, verifies its SHA256, and installs to $HOME/.local/bin/sendgrid. Pin with SENDGRID_TOOLKIT_VERSION=v0.2.0, change the directory with SENDGRID_TOOLKIT_INSTALL=$HOME/bin, add SENDGRID_TOOLKIT_MCP=1 to also install the sendgrid-mcp server binary.

Windows: download sendgrid-windows-x64.exe from the latest release and put it on PATH.

Updating:

sendgrid upgrade            # install latest (verifies sha256)
sendgrid upgrade --check    # report only

From source

git clone https://github.com/spenserhale/sendgrid-ai-toolkit && cd sendgrid-ai-toolkit
bun install
bun run dev:cli -- --help

Related MCP server: mail7-mcp

Teach your AI agents about the CLI

If you use Claude Code or any agent that supports open agent skills, install the sendgrid-cli skill so the agent reaches for the CLI whenever someone asks "why isn't this customer getting our email?":

npx skills add spenserhale/sendgrid-ai-toolkit@sendgrid-cli

The skill is generated from the live command tree (bun run build:skill) and CI fails if it drifts. For a machine-readable schema at runtime, run sendgrid agent-context.

Packages

Getting started

bun install
cp .env.example .env      # add your account keys
bun run dev:cli -- accounts        # sanity check: prints configured account names
bun run dev:cli -- diagnose someone@example.com

Configuration

The nearest .env above the working directory is loaded automatically; real env vars win.

Each API key needs read access to Suppressions and ASM (unsubscribe groups), plus Email Activity read access. Email Activity search also requires SendGrid's paid Email Activity History add-on on that account; without it the messages source is reported as unavailable, not as empty.

CLI

sendgrid diagnose <email>                 investigate one address across every account
sendgrid clear <email>                    remove from every suppression list it is on
sendgrid messages [--email|--query]       search Email Activity (last --days, default 30)
sendgrid blocks|bounces                   list|get|delete
sendgrid spam-reports|invalid-emails      list|delete
sendgrid global-suppressions              check|add|delete
sendgrid unsubscribe-groups               list|check|delete --group <id>
sendgrid accounts                         list configured account names
sendgrid agent-context                    machine-readable schema of everything above
sendgrid upgrade                          self-update the standalone binary

Output. Every command takes --format text|json|toon (or --text / --json / --toon). Text is the default for humans; JSON for integrations; TOON for coding agents. Set SENDGRID_OUTPUT to change the default.

Scope. Read commands hit every account unless --account <name> narrows them. Write commands (delete, clear, add) require --account <name> or --all-accounts and accept --dry-run. There is no implicit "everywhere".

Exit codes. 0 success or dry run (partial per-account failures are reported inline and still exit 0), 1 network/timeout/API, 2 validation, 3 config, 4 not found, 5 auth, 6 rate limit. When every account fails, the exit code is the first failure's.

MCP

See packages/mcp/README.md for the tool list, the destructive-tool contract, and Claude Desktop setup. Headline tools: diagnose_email and clear_suppressions.

Architecture

packages/sdk/     <-- Types, API client, AccountManager (fan-out, diagnose, clear)
    ^       ^
    |       |
packages/cli/   packages/mcp/
    (Stricli)    (FastMCP)

Both consumers are thin: all SendGrid knowledge lives in the SDK. AccountManager.runAcrossAccounts uses Promise.allSettled, so one revoked key yields a structured per-account error rather than failing the call.

Development

bun run test        # vitest via vite-plus
bun run lint        # oxlint
bun run typecheck   # tsc --noEmit for every package
bun run vocab-lint  # command/flag naming consistency, from the live route tree
bun run check       # formatting
bun run build:skill # regenerate sendgrid-cli/SKILL.md
bun run compile     # local standalone binaries into dist/ (CI builds the release matrix)

Releases: push a v* tag. The Release workflow tests, compiles CLI + MCP binaries for linux/darwin (x64, arm64) and windows-x64, attaches them with SHA256 checksums, and publishes a GitHub Release that scripts/install.sh and sendgrid upgrade consume.

Adding an API operation

1. Types in packages/sdk/src/types.ts

2. Client method in packages/sdk/src/client.ts (+ a test in packages/sdk/tests/client.test.ts)

3. CLI command in packages/cli/src/commands/, using emit() for text/json/toon and a placeholder on each positional

4. MCP tool in packages/mcp/src/tools/, with annotations and (if it writes) scopeParams

5. bun run vocab-lint && bun run build:skill