메시지

발신 이메일 전송, 수신함의 메시지 나열, 단일 메시지 조회, 메시지 삭제.

ⓘ

All requests require the x-api-key header. The base URL for every endpoint is https://api.agentsend.io.

Message 객체

메시지를 반환하는 모든 엔드포인트는 이 형식을 반환합니다.

json

{
  "id": "msg_01hx9k2v3w4x5y6z7a8b9c0d",
  "inboxId": "ibx_01hx9k2v3w4x5y6z7a8b9c0d",
  "threadId": "thr_01hx9k2v3w4x5y6z7a8b9c0d",
  "direction": "outbound",
  "fromAddress": "agent@yourdomain.com",
  "toAddresses": ["customer@example.com"],
  "ccAddresses": [],
  "subject": "Hello from AgentSend",
  "bodyText": "This email was sent by an AI agent.",
  "bodyHtml": "<p>This email was sent by an AI agent.</p>",
  "delivery": "email",
  "status": "delivered",
  "attachments": [],
  "messageIdHeader": "<msg_01hx9k2v...@agentsend.io>",
  "createdAt": "2026-04-16T10:23:00.000Z"
}

필드	타입	설명
`id`	string (uuid)	메시지의 고유 식별자.
`inboxId`	string (uuid)	이 메시지가 속한 수신함.
`threadId`	string (uuid)	이 메시지가 속한 스레드.
`direction`	enum	발신 메시지는 `outbound`, 수신 메시지는 `inbound`.
`fromAddress`	string	발신자 이메일 주소.
`toAddresses`	string[]	주 수신자 이메일 주소.
`ccAddresses`	string[]	참조 수신자 이메일 주소.
`subject`	string	이메일 제목.
`bodyText`	string \| null	일반 텍스트 본문.
`bodyHtml`	string \| null	HTML 본문.
`delivery`	enum	AgentSend가 메시지를 SES에 전달한 경우 `email`, 이 환경이 실제로 메일을 보내지 않고 전송을 시뮬레이션한 경우 `dry-run`.
`status`	enum	현재 전송 상태. `queued`, `sending`, `sent`, `delivered`, `failed`, `bounced`, `complained`, `received` 중 하나.
`attachments`	AttachmentMeta[]	첨부파일 메타데이터 객체 배열 (id, filename, contentType, size).
`messageIdHeader`	string	RFC 5322 `Message-ID` 헤더 값.
`createdAt`	string (ISO 8601)	메시지가 생성된 시각.

메시지 전송

POST /inboxes/{inboxId}/messages

수신함에서 발신 이메일을 보냅니다. 메시지는 즉시 큐에 들어가며 새 Message 객체와 함께 202 Accepted를 반환합니다. delivery를 확인해 환경이 실제 메일을 보냈는지(email) 시뮬레이션만 했는지(dry-run) 확인하세요. 전송 상태 업데이트는 웹훅 또는 GET /messages/{id} 폴링으로 확인할 수 있습니다.

경로 파라미터

파라미터	타입	설명
`inboxId` 필수	string (uuid)	전송할 수신함의 ID.

요청 본문

파라미터	타입	설명
`to` 필수	string[]	하나 이상의 수신자 이메일 주소.
`subject` 필수	string	이메일 제목. 최대 998자.
`cc`	string[]	참조 수신자 이메일 주소.
`bcc`	string[]	숨은참조 수신자 이메일 주소. 다른 수신자에게 보이지 않습니다.
`bodyText`	string	일반 텍스트 본문. `bodyText` 또는 `bodyHtml` 중 하나 이상을 제공해야 합니다.
`bodyHtml`	string	HTML 본문. HTML만 제공되면 AgentSend가 자동으로 텍스트 대체를 생성합니다.
`threadId`	string (uuid)	이 메시지를 기존 스레드에 연결합니다. 생략하면 새 스레드가 생성됩니다.
`attachmentIds`	string[] (uuid)	포함할 미리 업로드된 첨부파일 ID들. 먼저 첨부파일 API로 파일을 업로드하세요.

요청 예시

javascript

const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}/messages`,
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.AGENTSEND_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      to: ["customer@example.com"],
      cc: ["manager@example.com"],
      subject: "Your order is confirmed",
      bodyText: "Hi, your order #1234 has been confirmed.",
      bodyHtml: "<p>Hi, your order <strong>#1234</strong> has been confirmed.</p>",
      attachmentIds: ["att_01hx9k2v3w4x5y6z7a8b9c0d"],
    }),
  }
);

const message = await res.json();
console.log(message.id, message.status); // "msg_...", "queued"

Response — 202 Accepted

json

{
  "id": "msg_01hx9k2v3w4x5y6z7a8b9c0d",
  "inboxId": "ibx_01hx9k2v3w4x5y6z7a8b9c0d",
  "threadId": "thr_01hx9k2v3w4x5y6z7a8b9c0d",
  "direction": "outbound",
  "fromAddress": "agent@yourdomain.com",
  "toAddresses": ["customer@example.com"],
  "ccAddresses": ["manager@example.com"],
  "subject": "Your order is confirmed",
  "bodyText": "Hi, your order #1234 has been confirmed.",
  "bodyHtml": "<p>Hi, your order <strong>#1234</strong> has been confirmed.</p>",
  "delivery": "email",
  "status": "queued",
  "attachments": [
    {
      "id": "att_01hx9k2v3w4x5y6z7a8b9c0d",
      "filename": "invoice.pdf",
      "contentType": "application/pdf",
      "size": 204800
    }
  ],
  "messageIdHeader": "<msg_01hx9k2v3w4x5y6z7a8b9c0d@agentsend.io>",
  "createdAt": "2026-04-16T10:23:00.000Z"
}

메시지 목록

GET /inboxes/{inboxId}/messages

수신함의 메시지를 createdAt 내림차순으로 페이지네이션된 목록으로 반환합니다. status 필터를 사용해 특정 전송 상태의 메시지만 가져올 수 있습니다 — 예: status=received는 에이전트가 처리할 수신 메시지를 가져옵니다.

경로 파라미터

파라미터	타입	설명
`inboxId` 필수	string (uuid)	메시지를 나열할 수신함.

쿼리 파라미터

파라미터	타입	설명
`limit`	integer	반환할 메시지 수. 기본값 `20`. 최대 `100`.
`offset`	integer	페이지네이션을 위해 건너뛸 메시지 수. 기본값 `0`.
`status`	enum	전송 상태로 필터링. `queued`, `sending`, `sent`, `delivered`, `failed`, `bounced`, `complained`, `received` 중 하나.

요청 예시

javascript

const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}/messages?status=received&limit=50`,
  {
    headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  }
);

const { data, total } = await res.json();

for (const msg of data) {
  console.log(msg.fromAddress, msg.subject);
}

Response — 200 OK

json

{
  "data": [
    {
      "id": "msg_01hx9k2v3w4x5y6z7a8b9c0d",
      "inboxId": "ibx_01hx9k2v3w4x5y6z7a8b9c0d",
      "threadId": "thr_01hx9k2v3w4x5y6z7a8b9c0d",
      "direction": "inbound",
      "fromAddress": "customer@example.com",
      "toAddresses": ["agent@yourdomain.com"],
      "ccAddresses": [],
      "subject": "Re: Your order is confirmed",
      "bodyText": "Thanks! Can I change the delivery address?",
      "bodyHtml": null,
      "status": "received",
      "attachments": [],
      "messageIdHeader": "<abc123@mail.example.com>",
      "createdAt": "2026-04-16T10:45:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

메시지 조회

GET /messages/{id}

ID로 단일 메시지를 가져옵니다. 전송 후 전송 상태 업데이트를 폴링하는 데 사용하세요.

경로 파라미터

파라미터	타입	설명
`id` 필수	string (uuid)	가져올 메시지의 ID.

요청 예시

javascript

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

const message = await res.json();
console.log(message.status); // "delivered"

Response — 200 OK

단일 Message 객체를 반환합니다.

json

{
  "id": "msg_01hx9k2v3w4x5y6z7a8b9c0d",
  "inboxId": "ibx_01hx9k2v3w4x5y6z7a8b9c0d",
  "threadId": "thr_01hx9k2v3w4x5y6z7a8b9c0d",
  "direction": "outbound",
  "fromAddress": "agent@yourdomain.com",
  "toAddresses": ["customer@example.com"],
  "ccAddresses": [],
  "subject": "Your order is confirmed",
  "bodyText": "Hi, your order #1234 has been confirmed.",
  "bodyHtml": "<p>Hi, your order <strong>#1234</strong> has been confirmed.</p>",
  "delivery": "email",
  "status": "delivered",
  "attachments": [],
  "messageIdHeader": "<msg_01hx9k2v3w4x5y6z7a8b9c0d@agentsend.io>",
  "createdAt": "2026-04-16T10:23:00.000Z"
}

메시지 삭제

DELETE /messages/{id}

메시지를 영구적으로 삭제합니다. 이 작업은 취소할 수 없습니다. 메시지 삭제는 전송을 취소하지 않습니다 — 이메일이 이미 수신자에게 발송되었다면 회수할 수 없습니다.

⚠

스레드의 유일한 메시지를 삭제하면 해당 스레드도 삭제됩니다.

경로 파라미터

파라미터	타입	설명
`id` 필수	string (uuid)	삭제할 메시지의 ID.

요청 예시

javascript

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

Response — 204 No Content

성공 시 빈 본문을 반환합니다.

전송 상태

발신 메시지의 status 필드는 다음 상태를 거칩니다. 수신 메시지는 status: "received"로 도착합니다.

상태	설명
`queued`	메시지가 수락되어 발송 대기 중.
`sending`	수신자 메일 서버로 전송 중.
`sent`	수신자 메일 서버에서 수락됨.
`delivered`	수신자 메일함에 전송 확인됨 (지원되는 경우).
`failed`	영구 전송 실패. 자세한 내용은 웹훅 이벤트를 확인하세요.
`bounced`	하드 바운스 — 주소가 존재하지 않거나 서버가 전송을 거부했습니다.
`complained`	수신자가 메시지를 스팸으로 표시했습니다.
`received`	수신함에 수신된 수신 메시지.

💡

GET 엔드포인트를 폴링하는 대신 웹훅을 구독해 실시간 상태 전환을 받으세요.

← 이전 API: 수신함 다음 → API: 스레드