APIリファレンス

The AgentSend REST API. All requests and responses use JSON. Base URL: https://api.agentsend.io.

概要

AgentSend APIは、エージェントに受信トレイ、メッセージ、スレッド、Webhook、ドメイン、添付ファイル、アカウント設定へのプログラムアクセスを提供するREST APIです。すべてのリクエストとレスポンスボディはJSONです。

すべてのAPIエンドポイントは以下のベースURLで利用可能です：

base url

https://api.agentsend.io

ⓘ

For local development, the API is available at http://localhost:3000 when running the server locally.

認証

The AgentSend API supports two authentication methods. You only need one per request.

Bearerトークン

Pass your API key as a Bearer token in the Authorization header. This is the preferred method for server-side requests.

curl

curl https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>"

APIキーヘッダー

Alternatively, pass your API key directly in the x-api-key header.

curl

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.

リクエスト形式

Send request bodies as JSON and include a Content-Type: application/json header on all requests that have a body.

curl

curl -X POST https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Support Agent"}'

ページネーション

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:

json — paginated response

{
  "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.

エラーハンドリング

Errors return a JSON body with an error object containing a machine-readable code, a human-readable message, and the HTTP status.

json — error response

{
  "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.

レート制限

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.

べき等性

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

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セクション

各リソースの完全なリファレンスを参照してください：

📩

受信トレイ

エージェントの受信トレイを作成、更新、削除。アカウントのすべての受信トレイを一覧表示。

✉

メッセージ

送信メールの送信と受信トレイの受信メッセージの一覧表示。

💬

スレッド

件名と参加者でグループ化された会話スレッドの一覧表示と管理。

🔌

Webhook

リアルタイムイベント通知を受信するエンドポイントを登録。

🌐

ドメイン

カスタム送信ドメインの追加とDNS検証の管理。

⚙

アカウント

アカウント詳細の取得、APIキーの管理、使用状況の確認。

📎

添付ファイル

ファイルをアップロードして送信メッセージに添付。

← 前へインテグレーション次へ → API: 受信トレイ