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.
1. Check the credential first
Section titled “1. Check the credential first”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.
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.
2. Read the error, then decide
Section titled “2. Read the error, then decide”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. |
3. Retry only what’s safe to repeat
Section titled “3. Retry only what’s safe to repeat”Retry 429, 5xx and timeouts; never retry a 4xx unchanged. Some calls are safe to repeat as they are:
PUT /contactscreates 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.
4. Page through lists with the cursor
Section titled “4. Page through lists with the cursor”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 = nulldo { 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)5. Read what didn’t happen
Section titled “5. Read what didn’t happen”Batch calls say what they skipped instead of failing outright, so a 200 doesn’t mean every item went through:
POST /eventsrecords up to 100 events and lists the positions of those whose contact doesn’t exist innotFound. 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.
7. Pin the API version
Section titled “7. Pin the API version”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.
- API reference: every route, its permissions and its errors.
- Send events to an agent: signed events, as they happen.