API conventions

Every call uses the same auth, the same error envelope, and the same list shape. The figures below are the ones the API enforces.

Auth

Send Authorization: Bearer and a key. A key from POST /api-keys starts with as_. full_access can manage the account. sending_access can send and read mail. Creating and rotating keys is on API keys.

The envelope

A refusal carries code, message, fix and docs_url. retryable is true only when sending the same request later can succeed, and then retry_after_seconds is present. The error catalogue lists all 102 codes.

Idempotency

Send Idempotency-Key on every mutating call. The same key and the same body replay the first response. A different body with a key already stored is refused. The key is remembered for 7 days.

Rate limits

A new key allows 600 requests in 60 seconds. Every response carries ratelimit-limit, ratelimit-remaining and ratelimit-reset. When a call is refused for pace, wait the seconds in retry_after_seconds and send the same request. How do I handle rate limits? is the longer page.

Pagination

List endpoints return object, data, has_more and next_cursor. Ask for at most 100 rows. Pass the returned next_cursor as cursor on the next call. GET /emails shows the field:

curl -sS -X GET https://api.agentisend.com/emails \
  -H "Authorization: Bearer $AGENTISEND_API_KEY"

200
{
  "data": [],
  "has_more": false,
  "next_cursor": "example",
  "object": "list"
}

Request ids

Every response carries x-request-id. Quote it when you write to hello@agentisend.com about one call. The same value is on the row from GET /logs.

Next

• Quickstart
• SDKs
• Error catalogue