Avoiding duplicate sends

What to do when your agent retries a send and you're not sure whether the first one went through.

The scenario

Agent calls POST /send. The response times out. Did the message go or not? Naive retry risks sending twice.

What the API gives you today

Every sent message has a unique messageId returned in the response. You can cross-check by listing recent outbound messages:

curl "https://myagentmail.com/v1/inboxes/$ID/messages?direction=outbound&limit=10" \
  -H "X-API-Key: ak_..."

Scan the results for a matching subject and to within the last few seconds. If it's there, your first send succeeded — don't retry.

What's coming

A first-class Idempotency-Key header is on the roadmap. Send the same key twice and the second call returns the first call's response without sending again. If that's blocking you, let us know.

Design advice until then

• If a POST /send call times out or returns a 5xx, don't retry immediately. List recent messages first to check whether the send went through.
• For agent flows where duplicates are catastrophic (e.g. sending contracts), use drafts as a staging step. An agent can't accidentally send a draft twice — the second POST /drafts/{id}/send call returns a 404 because the first one deleted the draft.