메시지

메시지는 수신함에서 보내거나 받은 개별 이메일을 나타냅니다. 풍부한 HTML 이메일을 보내고, 전송 상태를 추적하고, 수신한 답장을 읽으세요.

개요

메시지는 수신함에 연결된 단일 이메일입니다. 에이전트가 이메일을 보내면 발신 메시지가 생성됩니다. 누군가 에이전트 주소로 답장하거나 이메일을 보내면 수신 메시지가 자동으로 생성됩니다.

모든 메시지는 스레드에 속합니다. 답장의 경우 기존 스레드에, 새로운 대화가 시작되면 자동으로 생성되는 새 스레드에 속합니다.

이메일 보내기

POST /inboxes/{inboxId}/messages

수신함의 messages 엔드포인트로 POST하여 이메일을 보냅니다. to 배열과 subject는 필수이며 나머지는 선택 사항입니다.

요청 본문

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"],
      subject: "Following up on your request",
      bodyText: "Hi, just checking in on your request.",
      bodyHtml: "<p>Hi, just checking in on your request.</p>",
    }),
  }
);

const message = await res.json();
console.log(message.id);     // msg_abc123
console.log(message.delivery); // "email" or "dry-run"
console.log(message.status); // "queued"

메시지 속성

API가 반환하는 각 메시지 객체는 다음 필드를 갖습니다.

메시지 상태

발신 메시지는 전송 라이프사이클을 거칩니다. 먼저 delivery를 확인해 환경이 실제 메일을 보냈는지 시뮬레이션만 했는지 확인한 다음, status 또는 웹훅을 사용해 공급자 측 라이프사이클을 추적하세요.

발신 라이프사이클

• queued — 메시지가 수락되었고 전송 대기 중입니다.
• sending — 메시지가 수신자의 메일 서버로 전송 중입니다.
• sent — 메시지가 수신자 메일 서버에 의해 수락되었습니다.
• delivered — 전송이 확인되었습니다 (수신 서버에서 지원하는 경우).

실패 상태

• failed — 일시적 또는 영구적 오류로 전송이 실패했습니다. 자세한 원인은 웹훅 페이로드를 확인하세요.
• bounced — 수신자 주소가 존재하지 않거나 서버가 메시지를 영구적으로 거부했습니다.
• complained — 수신자가 이메일을 스팸으로 신고했습니다.

수신 메시지

• received — 외부 발신자로부터 이메일이 수신함에 도착했습니다.

메시지 목록 조회

GET /inboxes/{inboxId}/messages

수신함의 메시지를 페이지네이션된 목록으로 가져옵니다. 상태별로 필터링하여 수신 답장, 전송 실패 등을 찾을 수 있습니다.

// Fetch the 10 most recent inbound messages
const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}/messages?status=received&limit=10`,
  { 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, msg.bodyText);
}

HTML vs 일반 텍스트

AgentSend는 일반 텍스트, HTML, 멀티파트 이메일을 지원합니다. 일반 텍스트는 bodyText, HTML 콘텐츠는 bodyHtml을 사용하세요.

• bodyText만 제공하면 이메일은 text/plain으로 전송됩니다.
• bodyHtml만 제공하면 이메일은 text/html로 전송됩니다.
• 둘 다 제공하면 이메일은 multipart/alternative로 전송됩니다. HTML을 지원하는 이메일 클라이언트는 HTML 버전을 표시하고, 그렇지 않은 경우 일반 텍스트 버전으로 대체됩니다.

메시지 삭제

DELETE /messages/{id}

ID로 메시지를 삭제합니다. 이는 AgentSend에서 메시지 레코드를 제거합니다. 이미 수신자 메일함에 전송된 이메일은 회수하지 않습니다.

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