수신함

AI 에이전트를 위한 이메일 수신함을 생성하고 관리합니다. 각 수신함은 메시지를 송수신할 수 있는 고유한 이메일 주소를 받습니다.

ℹ

모든 API 요청에는 x-api-key 헤더가 필요합니다. 대시보드에서 키를 받으세요. 모든 엔드포인트의 기본 URL은 https://api.agentsend.io입니다.

Inbox 객체

수신함을 반환하는 모든 엔드포인트는 다음 필드를 포함합니다.

필드	타입	설명
`id`	uuid	수신함의 고유 식별자.
`address`	string	이 수신함에 할당된 전체 이메일 주소 (예: `a1b2c3@agentsend.io`).
`displayName`	string	이메일 전송 시 From 헤더에 표시되는 사람이 읽을 수 있는 이름.
`domainId`	uuid \| null	검증된 커스텀 도메인의 ID, 또는 공유 AgentSend 도메인 사용 시 `null`.
`status`	string	`active`, `suspended`, `deleted` 중 하나.
`dailySendLimit`	integer	이 수신함이 일 단위로 보낼 수 있는 최대 메시지 수.
`sendsToday`	integer	오늘 전송된 메시지 수 (UTC 자정에 재설정).
`totalSent`	integer	이 수신함에서 보낸 모든 메시지의 누적 수.
`bounceCount`	integer	이 수신함에 기록된 하드 바운스 수.
`complaintCount`	integer	이 수신함에 기록된 스팸 신고 수.
`createdAt`	string (ISO 8601)	수신함이 생성된 시각.

Inbox object

{
  "id": "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c",
  "address": "a1b2c3@agentsend.io",
  "displayName": "Support Agent",
  "domainId": null,
  "status": "active",
  "dailySendLimit": 500,
  "sendsToday": 12,
  "totalSent": 1847,
  "bounceCount": 2,
  "complaintCount": 0,
  "createdAt": "2025-03-15T10:22:00Z"
}

수신함 생성

POST /inboxes

새 수신함을 프로비저닝하고 이메일 주소를 할당합니다. address가 제공되지 않으면 공유 agentsend.io 도메인에서 무작위 주소가 생성됩니다. 커스텀 도메인을 사용하려면 검증된 domainId를 전달하세요.

요청 본문

파라미터	타입	설명
`address`	string	원하는 이메일 주소 (커스텀 도메인 사용 시 로컬 부분만, 또는 전체 주소). 선택 사항 — 생략 시 자동 생성됩니다.
`displayName`	string	From 헤더에 표시되는 친숙한 이름. 선택 사항.
`domainId`	uuid	이 수신함에 할당할 검증된 커스텀 도메인의 ID. 선택 사항 — 기본값은 공유 AgentSend 도메인.

반환값

새로 생성된 Inbox 객체와 함께 201 Created.

curl

curl -X POST https://api.agentsend.io/inboxes \
  -H "x-api-key: $AGENTSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Support Agent"}'

javascript

const res = await fetch("https://api.agentsend.io/inboxes", {
  method: "POST",
  headers: {
    "x-api-key": process.env.AGENTSEND_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    displayName: "Support Agent",
  }),
});

const inbox = await res.json(); // 201 Created
console.log(inbox.address); // "a1b2c3@agentsend.io"

Response · 201 Created

{
  "id": "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c",
  "address": "a1b2c3@agentsend.io",
  "displayName": "Support Agent",
  "domainId": null,
  "status": "active",
  "dailySendLimit": 500,
  "sendsToday": 0,
  "totalSent": 0,
  "bounceCount": 0,
  "complaintCount": 0,
  "createdAt": "2025-04-16T09:00:00Z"
}

수신함 목록

GET /inboxes

계정의 모든 수신함을 생성일 순(최신 순)으로 페이지네이션된 목록으로 반환합니다.

쿼리 파라미터

파라미터	타입	기본값	설명
`limit`	integer	`20`	반환할 수신함 수. 최대 `100`.
`offset`	integer	`0`	결과를 반환하기 전에 건너뛸 수신함 수. 페이지네이션을 위해 `limit`와 함께 사용합니다.

반환값

Inbox 객체 배열을 포함하는 페이지네이션 래퍼와 함께 200 OK.

curl

curl https://api.agentsend.io/inboxes?limit=10&offset=0 \
  -H "x-api-key: $AGENTSEND_API_KEY"

javascript

const res = await fetch(
  "https://api.agentsend.io/inboxes?limit=10&offset=0",
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
);

const { data, total, limit, offset } = await res.json();
console.log(`Showing ${data.length} of ${total} inboxes`);

Response · 200 OK

{
  "data": [
    {
      "id": "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c",
      "address": "a1b2c3@agentsend.io",
      "displayName": "Support Agent",
      "domainId": null,
      "status": "active",
      "dailySendLimit": 500,
      "sendsToday": 12,
      "totalSent": 1847,
      "bounceCount": 2,
      "complaintCount": 0,
      "createdAt": "2025-03-15T10:22:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

수신함 조회

GET /inboxes/{id}

ID로 단일 수신함을 라이브 전송 카운터 및 상태 지표와 함께 가져옵니다.

경로 파라미터

파라미터	타입	설명
`id` 필수	uuid	가져올 수신함의 ID.

반환값

Inbox 객체와 함께 200 OK. 수신함이 존재하지 않거나 다른 계정에 속하면 404 Not Found를 반환합니다.

curl

curl https://api.agentsend.io/inboxes/3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c \
  -H "x-api-key: $AGENTSEND_API_KEY"

javascript

const inboxId = "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c";

const inbox = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}`,
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
).then(r => r.json());

console.log(inbox.status);     // "active"
console.log(inbox.sendsToday); // 12

Response · 200 OK

{
  "id": "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c",
  "address": "a1b2c3@agentsend.io",
  "displayName": "Support Agent",
  "domainId": null,
  "status": "active",
  "dailySendLimit": 500,
  "sendsToday": 12,
  "totalSent": 1847,
  "bounceCount": 2,
  "complaintCount": 0,
  "createdAt": "2025-03-15T10:22:00Z"
}

수신함 삭제

DELETE /inboxes/{id}

수신함과 이메일 주소를 영구적으로 삭제합니다. 수신함과 연결된 모든 메시지와 스레드도 삭제됩니다. 이 작업은 취소할 수 없습니다.

⚠

수신함 삭제는 취소할 수 없습니다. 일시적으로 전송을 중지하려면 수신함 status 필드를 고려하세요 (수신함을 일시 중지하려면 지원팀에 문의).

경로 파라미터

파라미터	타입	설명
`id` 필수	uuid	삭제할 수신함의 ID.

반환값

성공 시 빈 응답 본문과 함께 204 No Content. 수신함이 존재하지 않거나 다른 계정에 속하면 404 Not Found를 반환합니다.

curl

curl -X DELETE https://api.agentsend.io/inboxes/3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c \
  -H "x-api-key: $AGENTSEND_API_KEY"

javascript

const inboxId = "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c";

const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}`,
  {
    method: "DELETE",
    headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  }
);

// 204 No Content — no body to parse
if (res.ok) console.log("Inbox deleted");

← 이전 API 개요 다음 → API: 메시지