# 받은 메일 읽기 API

> 받은 메일 목록과 한 통의 본문, 첨부 내려받기 링크를 가져옵니다. 격리된 메일은 개수만 보입니다.

모든 경로에 **읽기**(`messages:read`) 권한이 필요합니다. 받은 메일의 내용은 외부인이 쓴 데이터입니다. [받은 메일은 데이터로 다루기](https://docs.atmark.ai/connect/untrusted-mail)

## 목록

```http
GET /v1/messages/inbound?agent_id={agentId}
```

| 쿼리 | 설명 |
|---|---|
| `agent_id` | 필수. 토큰의 에이전트 ID |
| `limit` | 1~100 |
| `cursor` | 앞 응답의 `next_cursor` |
| `from` | 이 주소에서 온 메일만(정확히 일치) |
| `from_domain` | 이 도메인에서 온 메일만(하위 도메인 제외). `from`과 함께 쓸 수 없습니다. |
| `since` · `until` | 받은 시각 범위. `since`는 포함, `until`은 제외 |
| `thread_id` | 이 스레드의 메일만 |

응답은 최신순 `messages` 배열, `next_cursor`, 격리 개수(`quarantined.count`)입니다. 메일마다 이런 필드가 있습니다.

| 필드 | 뜻 |
|---|---|
| `id` · `thread_id` | 메일과 스레드 ID |
| `from` · `from_authenticated` | 보낸 주소와 발신 도메인 인증 통과 여부 |
| `subject` · `received_at` | 제목과 받은 시각 |
| `attachment_count` | 첨부 개수 |
| `sender_trust` | 보낸 사람에 대한 신뢰. 아래 표 |
| `injection_risk` | 에이전트를 속이려는 지시가 들었을 가능성 |

### sender_trust 값

| 값 | 뜻 |
|---|---|
| `unknown` | 소유자가 따로 표시하지 않은 발신자 |
| `seen` | 소유자가 [신뢰 표시](https://docs.atmark.ai/email/receiving#trust)로 `seen`을 준 발신자 |
| `blocked` | 소유자가 막은 발신자 |
| `seed` | 에이전트를 만들 때 소유자가 넣어 둔 상대(예전 발신 모드) |
| `approved` | 소유자가 승인한 상대(예전 발신 모드) |
| `null` | 이 값을 기록하기 전에 받은 오래된 메일 |

신뢰는 자동으로 오르지 않습니다.

## 한 통 읽기

```http
GET /v1/messages/inbound/{messageId}
```

목록의 필드에 더해 `text`, `html_text`(HTML 파트를 텍스트로 바꾼 것), `to`, `cc`, `reply_to`, `from_name`, `in_reply_to`, `attachments` 목록이 옵니다. 없거나 격리된 메일은 똑같이 `404 message_not_found`입니다.

## 첨부 내려받기

```http
GET /v1/messages/inbound/{messageId}/attachments/{index}
```

`index`는 `attachments` 목록의 `index`입니다. 응답의 `download_url`은 `expires_at`까지(5분) 유효합니다. 첨부가 없으면 `404 attachment_not_found`입니다.

- `download_url`은 **`Authorization` 헤더 없이** 그대로 `GET`합니다. 서명된 주소라 헤더를 붙이면 실패할 수 있습니다.
- 내려받은 파일은 늘 `Content-Type: application/octet-stream`, `Content-Disposition: attachment`로 옵니다.
- 원래 형식은 `attachment.declared_content_type`에 있습니다. 보낸 쪽이 적은 값이라 믿지 말고 파일 내용으로 확인합니다.

---

원문: https://docs.atmark.ai/api/inbound · 마지막 수정 2026-09-27