SendGrid

Lightweight, dependency-free, in-memory SendGrid v3 Web API fake for testing code that uses the real @sendgrid/mail client.

Default port: 4650

Implemented Operations

Mail (the surface @sendgrid/mail actually calls)

• POST /v3/mail/send — accepts a SendGrid v3 mail payload, validates it like the real API, captures it in memory, and returns 202 Accepted with an empty body and an X-Message-Id response header. This is the single endpoint that @sendgrid/mail's send(), send([...]), and sendMultiple() hit.
• POST /v3/mail/batch — creates a batch_id for scheduled/batched sends (201, { batch_id }).
• GET /v3/mail/batch/:batch_id — validates a batch id (200, { batch_id }).

Account / key management (broader @sendgrid/client surface)

• GET /v3/scopes — lists the scopes available to the authenticated key.
• GET /v3/api_keys — lists API keys ({ result: [...] }).
• POST /v3/api_keys — creates an API key; returns the full api_key secret once (201).
• GET /v3/api_keys/:id — retrieves an API key (name + scopes).
• PUT|PATCH /v3/api_keys/:id — updates an API key's name/scopes.
• DELETE /v3/api_keys/:id — deletes an API key (204).

Unsubscribe groups & suppressions (ASM)

• GET /v3/asm/groups — lists unsubscribe groups (each { id, name, description, is_default, unsubscribes }).
• POST /v3/asm/groups — creates a group (201).
• GET /v3/asm/groups/:id — retrieves a group ({ id, name, description, is_default, unsubscribes }).
• PATCH|PUT /v3/asm/groups/:id — updates a group.
• DELETE /v3/asm/groups/:id — deletes a group (204).
• POST /v3/asm/suppressions/global — adds global unsubscribes ({ recipient_emails: [...] }, 201).
• GET /v3/asm/suppressions/global/:email — checks a global unsubscribe ({ recipient_email } or {}).
• DELETE /v3/asm/suppressions/global/:email — removes a global unsubscribe (204).

Sender verification

• GET /v3/verified_senders — lists verified senders ({ results: [...] }).
• POST /v3/verified_senders — registers a verified sender (201, auto-verified: true).

Service & inspection operations

• GET / — returns service metadata.
• GET /health — returns { "status": "ok" }.
• OPTIONS * — returns 204 (CORS preflight).
• GET /__parlel/messages — lists every captured outbound message ({ messages, count }).
• GET /__parlel/messages/:message_id — returns one captured message.
• DELETE /__parlel/messages — clears the captured mailbox only.
• POST /__parlel/reset — clears all in-memory state.
• server.reset() — clears all in-memory state when used in-process.

Quick Start

The fake speaks the exact wire protocol of the real client. Point @sendgrid/mail at the local server by overriding the client base URL:

import sgMail from "@sendgrid/mail";
import { SendgridServer } from "./services/sendgrid/src/server.js";

const server = new SendgridServer(4650);
await server.start();

sgMail.setApiKey("SG.parlel");
// Route the client to the local fake instead of api.sendgrid.com:
sgMail.client.setDefaultRequest("baseUrl", "http://127.0.0.1:4650");

const [response] = await sgMail.send({
  to: "test@example.com",
  from: "verified@parlel.dev",
  subject: "Sending with parlel is fun",
  text: "and easy to do anywhere, even with Node.js",
  html: "<strong>and easy to do anywhere, even with Node.js</strong>",
});

console.log(response.statusCode); // 202
console.log(response.headers["x-message-id"]);

await server.stop();

To assert what was "sent" in a test, read the captured mailbox:

const res = await fetch("http://127.0.0.1:4650/__parlel/messages");
const { messages, count } = await res.json();

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ supported · ◐ accepted (stored, not enforced) · ✓ by design · ⟳ on the roadmap.

Error Shapes

All JSON errors use SendGrid v3 framing — an errors array where each entry has message, field, and help:

{
  "errors": [
    {
      "message": "The subject is required. You can get around this requirement if you use a template with a subject defined or if every personalization has a subject defined.",
      "field": "subject",
      "help": "http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.subject"
    }
  ]
}

Returned status codes:

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

SENDGRID_API_KEY=SG.parlel
SENDGRID_BASE_URL=http://parlel-bridge:4650
SENDGRID_HOST=http://parlel-bridge:4650