Référence API
The AgentSend REST API. All requests and responses use JSON. Base URL: https://api.agentsend.io.
Overview
The AgentSend API is a REST API that gives your agents programmatic access to inboxes, messages, threads, webhooks, domains, attachments, and account settings. Every request and response body is JSON.
All API endpoints are available under the base URL:
https://api.agentsend.ioFor local development, the API is available at http://localhost:3000 when running the server locally.
Authentication
The AgentSend API supports two authentication methods. You only need one per request.
Bearer Token
Pass your API key as a Bearer token in the Authorization header. This is the preferred method for server-side requests.
curl https://api.agentsend.io/inboxes \
-H "Authorization: Bearer <your-api-key>"API Key Header
Alternatively, pass your API key directly in the x-api-key header.
curl https://api.agentsend.io/inboxes \
-H "x-api-key: <your-api-key>"Keep your API key secret. Never expose it in client-side code or commit it to version control. Use environment variables to pass it to your application.
Request Format
Send request bodies as JSON and include a Content-Type: application/json header on all requests that have a body.
curl -X POST https://api.agentsend.io/inboxes \ -H "Authorization: Bearer <your-api-key>" \ -H "Content-Type: application/json" \ -d '{"displayName": "Support Agent"}'
Pagination
Endpoints that return lists support limit and offset query parameters for pagination. The default limit is 20.
| Parameter | Type | Default | Description |
|---|---|---|---|
limit |
integer | 20 |
Maximum number of items to return. Max is 100. |
offset |
integer | 0 |
Number of items to skip before returning results. |
All list responses include a data array and a total count of all matching records:
{
"data": [ /* array of objects */ ],
"total": 142
}To fetch the next page, increment the offset by the limit value. For example, to get page 3 with a page size of 20: ?limit=20&offset=40.
Error Handling
Errors return a JSON body with an error object containing a machine-readable code, a human-readable message, and the HTTP status.
{
"error": {
"code": "INBOX_NOT_FOUND",
"message": "No inbox found with that ID.",
"status": 404
}
}Common HTTP status codes returned by the API:
| Status | Meaning |
|---|---|
400 |
Bad Request — the request body is missing required fields or contains invalid values. |
401 |
Unauthorized — no API key was provided, or the key is invalid. |
403 |
Forbidden — the API key does not have permission to perform this action. |
404 |
Not Found — the requested resource does not exist. |
409 |
Conflict — the resource already exists or the request conflicts with current state. |
429 |
Too Many Requests — you have exceeded your rate limit. Back off and retry. |
500 |
Internal Server Error — something went wrong on AgentSend's end. |
Rate Limiting
All API endpoints are rate-limited to protect platform stability. When you exceed the limit, the API returns a 429 Too Many Requests response.
Every API response includes rate limit headers so you can track your usage:
| Header | Description |
|---|---|
X-RateLimit-Limit |
Maximum number of requests allowed in the current window. |
X-RateLimit-Remaining |
Number of requests remaining in the current window. |
X-RateLimit-Reset |
Unix timestamp when the rate limit window resets. |
Use exponential backoff when retrying after a 429 response. Wait for the time indicated by X-RateLimit-Reset before sending additional requests.
Idempotency
POST requests can include an Idempotency-Key header to safely retry requests without creating duplicate resources. If a request with the same idempotency key is received within the idempotency window, the original response is returned instead of creating a new resource.
curl -X POST https://api.agentsend.io/inboxes \ -H "Authorization: Bearer <your-api-key>" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: my-unique-request-id-abc123" \ -d '{"displayName": "Support Agent"}'
API Sections
Browse the full reference for each resource: