Skip to content

Patterns for agents

The Sendwing API is built so an agent can work out what went wrong and fix it without a person. These patterns cover what agents most often get wrong. They apply to code calling the REST API; the MCP server handles most of them for you.

Before anything else, call GET /me. It says what the key or token is, which workspace it acts in, and gives the organizationId every other route needs, so the agent doesn’t guess it.

Terminal window
curl https://api.sendwing.app/api/me -H "x-api-key: $SENDWING_API_KEY"

A 401 here means the credential is wrong or revoked; no other call will work, so stop and ask for a new one.

Every error has the same shape: an HTTP status and a JSON body with error, in words you can show people.

{
"error": "Invalid request",
"issues": [{ "path": "events.0.name", "message": "Required" }]
}
Status Meaning What the agent should do
400 The request is wrong. issues lists each bad field by its path. Fix those fields and send again. Don’t retry it unchanged.
401 No valid credential. Stop, and ask for a working key.
402 The plan doesn’t allow it, like more contacts than it includes. Stop and tell a person; upgrading is their call.
403 The credential can’t do this. Stop: the key’s permissions, or the app’s scopes and the member’s role, don’t allow it.
404 It doesn’t exist in this workspace. Look it up again; don’t invent IDs.
409 It conflicts with the current state, like subscribing a contact who unsubscribed themselves. error says how. Don’t retry. Tell a person, or leave it.
429 Too many requests. Wait the seconds in Retry-After, then retry.
5xx Sendwing’s side failed. Retry with backoff. If it persists, report the requestId.

Retry 429, 5xx and timeouts; never retry a 4xx unchanged. Some calls are safe to repeat as they are:

  • PUT /contacts creates or updates the contact with that email or external id, so sending it twice leaves one contact.
  • Tagging, untagging and changing list subscriptions set a state; repeating them changes nothing.

Recording events (POST /events) is not: each call records new events, which can start a workflow again. Retry it only when you know the first attempt failed.

Lists are newest first, up to 100 at a time. Pass the response’s nextCursor as cursor until it comes back null. Don’t count pages or build offsets.

let cursor: string | null = null
do {
const url = new URL(`https://api.sendwing.app/api/organizations/${organizationId}/contacts`)
url.searchParams.set('limit', '100')
if (cursor) url.searchParams.set('cursor', cursor)
const page = await (await fetch(url, { headers: { 'x-api-key': key } })).json()
for (const contact of page.data) handle(contact)
cursor = page.nextCursor
} while (cursor)

Batch calls say what they skipped instead of failing outright, so a 200 doesn’t mean every item went through:

  • POST /events records up to 100 events and lists the positions of those whose contact doesn’t exist in notFound. Nothing creates a contact: add them first if they should exist.
  • Subscribing contacts to a mailing list lists in refused, with the reason, anyone who can’t be subscribed, like a contact who unsubscribed from that list themselves. Only they can subscribe again.

6. Sending happens later; watch for the outcome

Section titled “6. Sending happens later; watch for the outcome”

Starting a send isn’t the end. An email is sent, then delivered or bounced, minutes later. To know what happened, listen for email.delivered, email.bounced and email.failed with a webhook, or read the campaign’s report afterwards. Webhook events can arrive twice: skip any id you’ve already handled.

Send Sendwing-Version: 2026-10-27 on every request so a later API version can’t change the responses your agent expects. Every response says its version in the same header, and old versions are announced with Deprecation and Sunset headers at least six months before they go.