A SendGrid mock API that renders your templates and signs its webhooks

Connect

Import it. In Sonda: Import → From a URL, paste the OpenAPI address. You get a folder per resource and a request per operation, with example bodies and ids from the seed account, so most requests work as they are — the few that act on something you make first say so. Then set the auth: Bearer token SG.sondahub-sandbox. Any client that imports OpenAPI 3 takes the same address.

SendGrid’s SDKs know nothing about sondahub’s sessions, so give them the few lines that carry X-Sondahub-Session from one answer to the next request — otherwise every call starts from the seed account and the webhook you just made is not there.

Python (sendgrid-python)

import python_http_client
from sendgrid import SendGridAPIClient
from sendgrid.helpers.mail import Mail

sg = SendGridAPIClient('SG.sondahub-sandbox', host='https://api.sondahub.com')

# carry the sandbox session from each answer to the next request
_make = python_http_client.Client._make_request
def _keep(self, opener, request, timeout=None):
    res = _make(self, opener, request, timeout)
    token = res.headers.get('X-Sondahub-Session')
    if token:
        sg.client.request_headers['X-Sondahub-Session'] = token
    return res
python_http_client.Client._make_request = _keep

r = sg.send(Mail(from_email='[email protected]', to_emails='[email protected]',
                 subject='Hi', html_content='<p>It works.</p>'))
print(r.status_code, r.headers['X-Message-Id'], r.headers['X-Sondahub-Preview'])

Node (@sendgrid/mail)

import client from '@sendgrid/client'
import sgMail from '@sendgrid/mail'

client.setApiKey('SG.sondahub-sandbox')
client.setDefaultRequest('baseUrl', 'https://api.sondahub.com/')   // after setApiKey, which resets it

// carry the sandbox session from each answer to the next request
const request = client.request.bind(client)
client.request = async (data) => {
  const [res, body] = await request(data)
  const token = res.headers['x-sondahub-session']
  if (token) client.setDefaultHeader('X-Sondahub-Session', token)
  return [res, body]
}
sgMail.setClient(client)   // and no sgMail.setApiKey: it would put the host back

const [res] = await sgMail.send({ to: '[email protected]', from: '[email protected]', subject: 'Hi', html: '<p>It works.</p>' })

Try it here

curl -X POST https://api.sondahub.com/v3/mail/send \
  -H "Authorization: Bearer SG.sondahub-sandbox" \
  -H "Content-Type: application/json" \
  -d '{
    "personalizations": [{"to":[{"email":"[email protected]","name":"Ada"}]}],
    "from": {"email":"[email protected]","name":"Example Labs"},
    "subject": "Hello from the sandbox",
    "content": [{"type":"text/plain","value":"It works. Next step: https://example.com/next"},{"type":"text/html","value":"<p>It works. <a href=\"https://example.com/next\">Next step</a></p>"}],
    "categories": ["onboarding"],
    "custom_args": {"user_id":"42"}
  }'

curl -X POST https://api.sondahub.com/v3/mail/send \
  -H "Authorization: Bearer SG.sondahub-sandbox" \
  -H "Content-Type: application/json" \
  -d '{
    "personalizations": [{"to":[{"email":"[email protected]"}],"dynamic_template_data":{"first_name":"Grace","company":"Example Labs","trial_days":14,"login_url":"https://app.example.com/login","tips":["Invite your team","Connect a data source"]}}],
    "from": {"email":"[email protected]"},
    "template_id": "d-9e3779b1d4ee281dbf79a0e837f20e1e"
  }'

curl -X POST https://api.sondahub.com/v3/mail/send \
  -H "Authorization: Bearer SG.sondahub-sandbox" \
  -H "Content-Type: application/json" \
  -d '{
    "personalizations": [{"to":[{"email":"not-an-address"}]}],
    "from": {"email":"[email protected]"},
    "content": [{"type":"text/html","value":"<p>Hi</p>"},{"type":"text/plain","value":"Hi"}]
  }'

curl -X POST https://api.sondahub.com/v3/mail/send \
  -H "Authorization: Bearer SG.sondahub-sandbox" \
  -H "Content-Type: application/json" \
  -d '{
    "personalizations": [{"to":[{"email":"[email protected]"}]}],
    "from": {"email":"[email protected]"},
    "subject": "Hi",
    "content": [{"type":"text/plain","value":"Hi"}]
  }'

curl "https://api.sondahub.com/v3/messages?query=to_email%3D%22ada%2Bclick%40example.com%22&limit=5" \
  -H "Authorization: Bearer SG.sondahub-sandbox"

curl "https://api.sondahub.com/v3/suppression/bounces" \
  -H "Authorization: Bearer SG.sondahub-sandbox"

From the shell, keep the token yourself: curl -i shows X-Sondahub-Session; send it back with -H "X-Sondahub-Session: …". How sessions work.

What happens to each recipient

A recipient is processed at once and delivered a second and a half later — unless a +tag in the address says otherwise, or the address is on a suppression list. The tags work on any address, so your own test inboxes can bounce on purpose.

Opens need open tracking and an HTML part (the tracking pixel lives there); clicks need click tracking and a link in the HTML — or in the text, with click_tracking.enable_text. Both are on unless tracking_settings turns them off. A bounce, a spam report or an unsubscribe adds the address to its list, so the next send to it is dropped; a block goes on the blocks list, but later sends still go out, as at SendGrid. mail_settings.sandbox_mode validates and renders only: 200, nothing sent, no events — the preview link still comes back.

The Event Webhook, signed

Create up to five with POST /v3/user/webhooks/event/settings — your URL and the events you want (processed, delivered, deferred, bounce, dropped, open, click, spam_report, unsubscribe, group_unsubscribe) — and each recipient’s events are POSTed as a JSON array the moment they happen, with SendGrid’s fields: email, timestamp, event, sg_event_id, sg_message_id, smtp-id, category, your custom_args at the top level, and each event’s own (reason, status, type, url, attempt…). Retried after 1 and 3 seconds on a network error, 408, 429 or 5xx — the sandbox’s own short schedule, since it has half a minute to finish; SendGrid itself keeps retrying for hours.

Turn signing on with PATCH /v3/user/webhooks/event/settings/signed/{id} {"enabled": true}; the answer holds the public key. Then SendGrid’s own helpers verify every post:

Python

from sendgrid.helpers.eventwebhook import EventWebhook, EventWebhookHeader

# the public key: GET /v3/user/webhooks/event/settings/signed/{id}
ew = EventWebhook()
key = ew.convert_public_key_to_ecdsa(public_key)
ok = ew.verify_signature(request.get_data(as_text=True),
                         request.headers[EventWebhookHeader.SIGNATURE],
                         request.headers[EventWebhookHeader.TIMESTAMP], key)

Node

import { EventWebhook, EventWebhookHeader } from '@sendgrid/eventwebhook'

// express.raw({ type: 'application/json' }) — the signature covers the exact bytes
const ew = new EventWebhook()
const key = ew.convertPublicKeyToECDSA(publicKey)
const ok = ew.verifySignature(key, req.body, req.get(EventWebhookHeader.SIGNATURE()), req.get(EventWebhookHeader.TIMESTAMP()))

The legacy single-webhook paths (GET/PATCH /v3/user/webhooks/event/settings and …/settings/signed) work on the oldest webhook. POST /v3/user/webhooks/event/test sends two sample events to any URL. The hub-wide X-Sondahub-Webhook header on a send also gets every event, signed the same way (the webhook tester).

Dynamic templates

Send with template_id and each personalization’s dynamic_template_data, and the active version’s subject and HTML are rendered with the Handlebars SendGrid documents: {{name}} (escaped), {{{html}}}, a.b.c, {{#if}} / {{else if}} / {{else}}, {{#unless}}, {{#each}} with this, @index, @first, @last, ../, {{#with}}, {{#equals}}, {{#notEquals}}, {{#greaterThan}}, {{#lessThan}}, {{#and}}, {{#or}}, {{length}}, {{formatDate}} and {{insert name "default=…"}}. The plain-text part is made from the HTML unless the version has its own. Legacy templates put your content where <%body%> is, and substitutions work as before.

Make your own with POST /v3/templates {"name", "generation": "dynamic"} and POST /v3/templates/{id}/versions. Substitutions with a dynamic template are refused, as SendGrid refuses them.

Suppressions and unsubscribe groups

The bounce, block, spam report, invalid email and global unsubscribe lists start with a few addresses each and grow as your sends bounce, get blocked, get reported or unsubscribe. List, look up and delete them as at SendGrid. The seed account’s unsubscribe groups are 16401 Product updates and 16402 Account alerts: a send with asm.group_id drops the group’s unsubscribers, and a +unsubscribe recipient leaves that group (group_unsubscribe) rather than everything.

Email Activity and stats

GET /v3/messages?query=… filters the recipients of the seed account’s month of mail and of your session’s last 25 sends (the first 50 recipients of each) — to_email, from_email, subject, status (processed, delivered, not_delivered), msg_id, template_id, asm_group_id, last_event_time, with =, !=, LIKE "%…%", IN (…), BETWEEN TIMESTAMP "…" AND TIMESTAMP "…", Contains(categories, "…"), AND, OR, NOT and parentheses. GET /v3/messages/{msg_id} lists one recipient’s events. GET /v3/stats?start_date=… counts requests, deliveries, bounces, opens, clicks and the rest by day, week or month.

Simulate incoming mail (Inbound Parse)

SendGrid posts your app a multipart/form-data request when mail arrives at your parse hostname: headers, dkim, to, from, subject, text, html, envelope, charsets, SPF, sender_ip, attachments — or the whole MIME message as email with send_raw. This sends your webhook exactly that and shows what it answered.

What it answers

Errors are SendGrid’s: {"errors": [{"field", "message"}]} — Mail Send lists every problem at once, with SendGrid’s messages and a help link. The seed account has 60 contacts on 3 lists, 40 messages from the month before, two verified senders and the authenticated domain example.com. Contacts upserts and deletes answer with a job: upserted contacts appear two seconds later, deletes take effect at once.

Also on sondahub

Fake REST API · Public GraphQL API · gRPC-Web & Connect · WebSocket test server · SSE test server · Public MQTT broker · MCP test server · MCP OAuth test server · Writes that persist · OpenAPI mock server · Webhook tester · Chaos and rate limits · SAML test IdP and SP · SCIM 2.0 test server · OAuth 2.0 test server · Auth test endpoints · HTTP test endpoints · Fake JSON data · JSONPlaceholder alternative · Stripe sandbox · Twilio sandbox

The mock APIs themselves: fake e-commerce API, fake IoT API, fake banking API, fake social media API, fake helpdesk API, fake flight booking API, fake user directory API. Built as the playground for LockFlare Sonda, the API client that lives on your computer.