An email API you can reason about

Sending a message

One POST per message, scoped to a project and an inbox. Recipients are objects, not strings, and an Idempotency-Key header is required — the request is rejected without one.

curl -X POST \
  "https://api.emailforagents.ai/v1/projects/$PROJECT_ID/inboxes/$INBOX_ID/messages" \
  -H "Authorization: Bearer $EFA_API_KEY" \
  -H "Idempotency-Key: 6f1c2b2e-3a7d-4a2f-9f4e-2b0d1c7a8e55" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{ "email": "ap@example.com", "name": "Accounts Payable" }],
    "subject": "Q3 invoice",
    "text": "Attached.",
    "reply_to_message_id": "msg_..."
  }'

The call returns 202 with a request id. Sending is asynchronous: acceptance by the provider and delivery to the recipient arrive later, as separate events. No TypeScript or Python SDK is published yet, so everything here is plain HTTP.

Retrying without sending twice

Every send carries an idempotency key, and the server hashes a canonical form of the payload against it.

Knowing what happened

Poll the events endpoint with its cursor, or register a webhook and let it push. Both carry the same vocabulary.

curl "https://api.emailforagents.ai/v1/projects/$PROJECT_ID/events?cursor=$CURSOR" \
  -H "Authorization: Bearer $EFA_API_KEY"

Webhooks that behave

A webhook endpoint must be public HTTPS. The delivery service resolves the address, pins the connection to a public IP, verifies TLS, and refuses redirects and private networks.

• Signed, with a tolerance. Every delivery carries an HMAC signature over the timestamp and body. Reject anything more than 300 seconds old, then compare digests in constant time.

• A published retry schedule. Up to 8 attempts, at 10 seconds, 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours.

• 4xx stops the retries. Except 408, 409, 425 and 429, which are treated as "try again". A 500 is always retried.

• At-least-once, so deduplicate. Keep the event id you have already processed. Verify signatures and deduplicate events before acting on a callback.

Keys, limits and versioning