AgenticEmail: AI 에이전트를 위한 이메일은(는) 무엇을 하나요?
AgenticEmail은 에이전트가 소유하고 실제로 사용할 수 있는 이메일 수신함을 제공합니다. 단순히 발신만 가능한 API와 달리, 모든 수신함은 송수신이 모두 가능합니다. 수신 메일은 웹훅이나 WebSocket 스트림을 통해 구문 분석된 JSON으로 도착합니다. 에이전트가 이메일 주소로 연락 가능해야 할 때(단순히 보내기만 가능한 것이 아니라) 이 스킬을 사용하세요.
일반적인 사용 사례: 에이전트가 타사 서비스에 가입해야 하거나, 인증 코드/OTP를 수신해야 하거나, 이메일로 알림을 받아야 하거나, 지원 또는 아웃리치 워크플로우를 실행해야 하거나, 사람이나 다른 에이전트와 이메일을 주고받아야 할 때.
설정
- https://app.agenticemail.dev 에서 API 키를 발급받으세요. (키는
am_로 시작합니다.) 무료 티어에는 실제 수신함, 발신, 수신, 웹훅이 모두 포함됩니다. - 환경 변수로 내보냅니다:
export AGENTICEMAIL_API_KEY=am_... - 아래 통합 경로 중 하나를 선택하세요. 모든 경로는
https://api.agenticemail.dev를 호출합니다.
통합 경로 선택
- 호스티드 MCP 서버 (권장, MCP 지원 에이전트: Claude, Cursor, Vercel AI SDK 등).
https://api.agenticemail.dev/mcp에 API 키를 Bearer 토큰으로 연결하세요. 에이전트가 다음 도구를 직접 사용할 수 있습니다:create_inbox,list_inboxes,list_threads,get_thread,list_messages,get_message,send_message,reply_to_message. - CLI (
npm i -g agenticemail-cli): 셸 기반 에이전트용. - SDK (
npm i agenticemailfor TypeScript, orpip install 'agenticemail[e2e]'for Python): 코드 기반 통합용.
MCP 클라이언트 설정
HTTP 네이티브 클라이언트 (Claude, Cursor 등 streamable HTTP 지원 클라이언트):
{
"mcpServers": {
"agenticemail": {
"type": "http",
"url": "https://api.agenticemail.dev/mcp",
"headers": { "Authorization": "Bearer ${AGENTICEMAIL_API_KEY}" }
}
}
}
Stdio 전용 클라이언트는 브릿지를 사용하세요:
npx mcp-remote https://api.agenticemail.dev/mcp \
--header "Authorization: Bearer $AGENTICEMAIL_API_KEY"
핵심 워크플로우: 생성, 보내기, 받기, 답장
CLI:
INBOX=$(agenticemail inboxes create --username assistant | jq -r .id)
agenticemail messages send "$INBOX" --to [email protected] \
--subject "Hello" --text "Sent by an agent."
agenticemail messages list "$INBOX" --limit 5
agenticemail messages reply "$INBOX" <msgId> --text "On it."
agenticemail wait-for-message "$INBOX" --timeout 300
TypeScript SDK:
import { AgenticEmail } from "agenticemail";
const client = new AgenticEmail({ apiKey: process.env.AGENTICEMAIL_API_KEY! });
const inbox = await client.inboxes.create({ username: "assistant" });
await client.messages.send(inbox.id, {
to: ["[email protected]"],
subject: "Hello",
text: "Sent by an agent.",
});
const { data } = await client.messages.list(inbox.id, { limit: 5 });
const msg = await client.messages.get(inbox.id, data[0].id);
await client.messages.reply(inbox.id, msg.id, { text: "Thanks." });
Python SDK:
from agenticemail import AgenticEmail
client = AgenticEmail(api_key=os.environ["AGENTICEMAIL_API_KEY"])
inbox = client.inboxes.create(username="assistant")
client.messages.send(inbox.id, to=["[email protected]"], subject="Hello", text="...")
for m in client.messages.list(inbox.id, limit=5).data:
print(m.subject)
REST (SDK를 사용하지 않는 경우)
기본 URL https://api.agenticemail.dev, 헤더 Authorization: Bearer $AGENTICEMAIL_API_KEY.
| 메서드 | 경로 | 목적 |
|---|---|---|
| POST | /v1/inboxes | 수신함 생성. 본문 { "username": "assistant" } (선택 사항). |
| GET | /v1/inboxes | 수신함 목록 조회. |
| POST | /v1/inboxes/{id}/messages | 메시지 보내기. 본문 { "to": ["[email protected]"], "subject": "...", "text": "..." }. |
| GET | /v1/inboxes/{id}/messages | 메시지 목록 조회. 쿼리 limit, cursor. |
| GET | /v1/inboxes/{id}/messages/{msgId} | 단일 메시지 조회 (구문 분석됨). |
| POST | /v1/inboxes/{id}/messages/{msgId}/reply | 스레드 내에서 답장. |
| POST | /v1/webhooks | 웹훅 등록. 본문 { "url": "...", "eventTypes": ["message.received"] }. |
모든 메시지 객체는 encrypted 불리언 필드를 포함하므로 클라이언트가 복호화해야 하는지 알 수 있습니다.
인바운드 메일 수신
웹훅을 등록하면 새 메일이 도착하자마자 에이전트가 수신할 수 있습니다:
agenticemail webhooks create --url https://your-app/hook \
--event-types message.received
각 이벤트는 구문 분석된 발신자, 제목, 텍스트, HTML 및 첨부 파일을 전달합니다. 에이전트가 이미 실행 중인 경우 동일한 이벤트에 대해 WebSocket 스트림을 사용할 수 있습니다 (agenticemail events tail).
종단간 암호화 (선택 사항)
에이전트 간 메일의 경우, AgenticEmail은 선택적 종단간 암호화를 제공합니다. 개인 키는 클라이언트(SDK 또는 CLI)에서 생성 및 보관되며 서버에는 절대 저장되지 않으므로 플랫폼이 콘텐츠를 읽을 수 없습니다. CLI에서 agenticemail keys generate <inbox> 후 agenticemail keys publish <inbox>를 실행하여 활성화하면, messages send 및 messages get이 자동으로 암호화 및 복호화합니다. SDK에서는 클라이언트 생성 시 e2e ID를 전달합니다:
import { AgenticEmail, generateIdentity } from "agenticemail";
const client = new AgenticEmail({
apiKey: process.env.AGENTICEMAIL_API_KEY!,
e2e: { identity: generateIdentity(), autoPublish: true },
});
다음은 이것이 무엇을 보장하고 보장하지 않는지에 대한 정직한 설명입니다:
- 선택 사항이며, 키를 게시한 두 AgenticEmail 수신함 간에만 작동합니다. 기본값은 평문입니다.
- 개인 키는 클라이언트 측에만 있으며 서버에 절대 도달하지 않으므로, 플랫폼이나 해당 클라우드 제공자도 암호화된 콘텐츠를 읽을 수 없습니다.
- 외부 주소(Gmail, 기업 서버)로 보내는 경우 게시된 키가 없으므로 평문으로 대체됩니다.
- 라우팅 메타데이터(발신자, 수신자, 시간, 크기)는 SMTP 요구 사항에 따라 계속 표시됩니다.
- 개인 키를 분실하면 이전 암호화된 메일을 복구할 수 없습니다. 서버가 키를 보관하지 않는 대가입니다.