수신함

각 에이전트는 고유한 이메일 주소가 있는 자체 수신함을 받습니다. 수신함은 AgentSend의 기본 단위입니다.

개요

수신함은 단일 에이전트를 위한 전용 이메일 주소입니다. 에이전트가 보내거나 받는 모든 이메일은 수신함을 통해 흐릅니다. 에이전트마다, 고객마다, 워크플로마다 하나씩 — 필요한 만큼 수신함을 만들 수 있으며 제한이 없습니다.

기본적으로 수신함은 @agentsend.io 도메인에서 프로비저닝됩니다. 자체 도메인(예: agent@yourcompany.com)에서 보내려면 커스텀 도메인을 참고하세요.

ℹ

수신함은 서로 격리되어 있습니다. 에이전트는 자신의 수신함을 통해서만 이메일을 송수신할 수 있으며, 다른 수신함의 메시지에는 접근할 수 없습니다.

수신함 만들기

POST /inboxes

POST 요청을 보내 새 수신함을 만드세요. 두 본문 필드 모두 선택 사항입니다. displayName을 생략하면 이름 없이 생성되고, domainId를 생략하면 @agentsend.io에서 주소가 프로비저닝됩니다.

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",   // optional
    domainId: "dom_abc123",         // optional — omit for @agentsend.io
  }),
});

const inbox = await res.json();
console.log(inbox.address); // e.g. a1b2c3@agentsend.io
console.log(inbox.id);      // e.g. inb_7x9kQm2Np...

응답에는 즉시 사용할 수 있는 자동 생성된 address를 포함한 전체 수신함 객체가 포함됩니다.

수신함 속성

모든 수신함 객체는 다음 필드를 갖습니다:

속성	타입	설명
`id`	string (uuid)	수신함의 고유 식별자. 모든 API 호출에서 사용됩니다.
`address`	string (email)	이 수신함에 할당된 전체 이메일 주소 (예: `a1b2c3@agentsend.io`).
`displayName`	string \| null	수신함의 사람이 읽을 수 있는 레이블. 발신 이메일 헤더의 발신자 이름으로 표시됩니다.
`domainId`	string \| null	이 수신함에 연결된 커스텀 도메인의 ID. 기본 `@agentsend.io` 주소인 경우 `null`.
`status`	string	현재 수신함 상태: `active`, `suspended`, `deleted`. `active` 수신함만 송수신할 수 있습니다.
`dailySendLimit`	number	이 수신함이 24시간 동안 보낼 수 있는 최대 이메일 수.
`sendsToday`	number	현재 24시간 창에서 전송된 이메일 수. UTC 자정에 재설정됩니다.
`totalSent`	number	수신함 생성 이후 보낸 모든 이메일의 누적 수.
`bounceCount`	number	이 수신함에 기록된 하드 바운스 수. 바운스율이 높으면 일시 중지될 수 있습니다.
`complaintCount`	number	이 수신함에 기록된 스팸 신고 수.
`createdAt`	string (ISO 8601)	수신함이 생성된 시각.

커스텀 도메인

기본적으로 모든 수신함은 @agentsend.io에서 주소를 받습니다. 자체 도메인(예: agent@support.yourcompany.com)에서 보내려면 커스텀 도메인을 연결하고 수신함을 만들 때 domainId를 전달하세요.

💡

커스텀 도메인은 전송 가능성과 브랜드 신뢰도를 향상시킵니다. 도메인을 추가하고 확인하려면 도메인 가이드를 참고한 뒤 다시 돌아와 수신함을 만드세요.

수신함 목록 조회

GET /inboxes

계정의 모든 수신함을 페이지네이션된 목록으로 가져옵니다. limit와 offset으로 결과를 페이지 단위로 탐색하세요.

javascript

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

const { data, total } = await res.json();
// data  — array of inbox objects
// total — total count across all pages

for (const inbox of data) {
  console.log(inbox.address, inbox.status, inbox.sendsToday);
}

쿼리 파라미터	타입	설명
`limit`	number	반환할 결과 수. 기본값 `20`, 최대 `100`.
`offset`	number	건너뛸 결과 수. 기본값 `0`.

수신함 삭제

DELETE /inboxes/{id}

수신함과 관련된 모든 메시지, 스레드, 웹훅을 영구적으로 삭제합니다.

⚠

이 작업은 영구적이며 취소할 수 없습니다. 수신함에 속한 모든 메시지, 스레드, 웹훅 구독이 즉시 삭제됩니다. 수신함의 이메일 주소는 해제되어 재할당될 수 있습니다.

javascript

await fetch(`https://api.agentsend.io/inboxes/${inboxId}`, {
  method: "DELETE",
  headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
});
// Returns 204 No Content on success

전송 한도

각 수신함에는 롤링 24시간 창에서 보낼 수 있는 이메일 수를 제한하는 dailySendLimit이 있습니다. sendsToday 필드는 현재 창에서 사용된 전송 수를 알려줍니다.

수신함이 한도에 도달하면 이후 전송 요청은 429 Too Many Requests 오류를 반환합니다. 창은 UTC 자정에 재설정됩니다.

ℹ

대량 전송 전에 sendsToday를 모니터링하세요. 에이전트가 기본 한도를 초과하는 전송이 필요하면 지원팀에 연락하여 계정 한도 증액을 요청하세요.

javascript

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

const remaining = inbox.dailySendLimit - inbox.sendsToday;
if (remaining <= 0) {
  console.log("Daily send limit reached. Try again after midnight UTC.");
} else {
  console.log(`${remaining} sends remaining today`);
}

← 이전 시작하기 다음 메시지 →