Sendmux의 이메일 받은편지함 API + Sending

AI 에이전트를 위한 이메일 받은편지함 API, 인바운드 메일, 아웃바운드 발송 MCP 및 A2A 서버로, Sendmux를 통한 인바운드 이메일, 깔끔한 JSON 파싱, 웹훅, 다중 공급자 라우팅을 제공합니다.

이 패키지는 Sendmux MCP입니다. 문서 도구에서 사용하는 문서 검색 MCP와는 별도로 유지하세요.

문서

• Sendmux 문서: sendmux.ai/docs

• Management API 참조: sendmux.ai/docs/api/introduction

• Mailbox API 참조: sendmux.ai/docs/mailbox-api/introduction

• Sending API 참조: sendmux.ai/docs/sending-api/introduction

• 소스 저장소: Sendmux/sendmux-sdk

Related MCP server: mcp-server-lobstermail

요구 사항

• Python 3.10 이상.

• Sending 도구에는 발송 가능한 smx_mbx_* 키 또는 소유자 승인 Sending 리소스 smx_agent_* 토큰이 필요합니다.

• Mailbox 도구에는 사서함 범위의 smx_mbx_* 키 또는 범위가 지정된 smx_agent_* 토큰이 필요합니다.

• Management 도구에는 루트 smx_root_* 키가 필요합니다.

설치

pip install sendmux-mcp

사용법

표면별 명령으로 단일 로컬 서버를 실행합니다.

SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-mailbox
SENDMUX_API_KEY=smx_root_... sendmux-mcp-management
SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-sending

sendmux-mcp로 결합된 로컬 서버를 실행합니다.

SENDMUX_MCP_SURFACES=mailbox,sending \
SENDMUX_MAILBOX_API_KEY=smx_mbx_... \
SENDMUX_SENDING_API_KEY=smx_mbx_... \
sendmux-mcp

두 키 유형이 모두 있을 때 세 가지 로컬 표면을 모두 실행합니다.

SENDMUX_MCP_SURFACES=mailbox,management,sending \
SENDMUX_MAILBOX_API_KEY=smx_mbx_... \
SENDMUX_MANAGEMENT_API_KEY=smx_root_... \
SENDMUX_SENDING_API_KEY=smx_mbx_... \
sendmux-mcp

일반 sendmux-mcp 명령은 --surface 또는 --surfaces도 허용합니다. 래퍼 명령은 정확히 하나의 표면을 선택합니다.

전송

stdio는 로컬 에이전트 클라이언트의 기본 전송입니다.

SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-mailbox --transport stdio

http 및 streamable-http는 HTTP를 통해 MCP 엔드포인트를 노출합니다. HTTP 모드는 기본적으로 127.0.0.1:8765/mcp이며, 명시적으로 옵트아웃하지 않는 한 별도의 MCP 베어러 토큰이 필요합니다.

SENDMUX_API_KEY=smx_mbx_... \
SENDMUX_MCP_HTTP_BEARER_TOKEN=local-mcp-token \
sendmux-mcp-mailbox --transport http --host 127.0.0.1 --port 8765 --path /mcp

/health는 선택된 표면에 대한 작은 JSON 상태 응답을 반환합니다.

호스팅 엔드포인트

공개 호스팅 MCP 엔드포인트는 https://mcp.sendmux.ai/mcp입니다.

호스팅 클라이언트의 경우 OAuth와 함께 HTTP 전송을 사용하세요. 클라이언트가 명시적으로 요구하지 않는 한 수동 Authorization 헤더, API 키, 사용자 지정 OAuth 엔드포인트 또는 사용자 지정 범위를 추가하지 마세요.

등록 또는 인증 중에 요청된 범위를 생략하는 호스팅 OAuth 클라이언트가 지원됩니다. 서버는 검색 및 베어러 챌린지를 통해 호스팅 범위 집합을 광고합니다.

패키지에 포함된 sendmux-mcp-hosted 명령은 호스팅 서버 런타임을 실행합니다. 호환되는 OAuth 기반 호스팅 환경을 운영하지 않는 한 로컬 및 프라이빗 배포는 위의 로컬 명령을 사용해야 합니다.

호스팅 A2A 엔드포인트

동일한 호스팅 런타임은 https://a2a.sendmux.ai/a2a/v1에서 HTTP+JSON을 통한 결정적 A2A 1.0을 노출합니다. https://a2a.sendmux.ai/.well-known/agent-card.json에서 검색할 수 있습니다. OAuth 리소스 메타데이터는 https://a2a.sendmux.ai/.well-known/oauth-protected-resource에 있습니다.

A2A message:send 작업에 정확히 하나의 JSON DataPart를 보내세요. 해당 데이터는 선별된 Sendmux 작업을 선택하고 해당 작업의 입력을 제공합니다:

{
  "operationId": "managementListDomains",
  "pathParameters": {},
  "query": { "limit": 10 },
  "headers": {},
  "body": null,
  "mailboxId": null
}

operationId는 호스팅 MCP 서비스와 동일한 선별된 작업 ID를 사용합니다. OAuth 부여는 A2A 리소스에 대상이 바인딩되며 Sendmux 표면 및 권한 제한을 유지합니다. 서비스는 업스트림 상태, 안전한 응답 헤더 및 JSON 본문(비 JSON 응답의 경우 bodyBase64)을 포함하는 하나의 JSON DataPart를 반환합니다.

A2A 엔드포인트는 즉각적이고 상태 비저장입니다. 스트리밍, 푸시 알림, 영구 작업 및 작업 취소는 광고되거나 라우팅되지 않습니다.

구성

패키지된 OpenAPI 스냅샷이 기본값이므로 릴리스된 도구 이름, 스키마 및 설명이 안정적으로 유지됩니다. 개발, 카나리 및 디버깅 실행을 위해 경로, 디렉터리 및 URL 재정의를 사용할 수 있습니다.

도구 표면

• Mailbox: 허용된 사서함, 프로필/세션 검색, 메시지, 첨부 파일, 제한된 메시지 대기, 스레드, 폴더, 검색, 개수 및 사서함 발송을 위한 25개 도구. smx_mbx_* 키 또는 범위가 지정된 smx_agent_* 토큰이 필요합니다. 에이전트 토큰은 서버 측 범위에 의해 계속 제한됩니다. 사전 클레임된 자체 등록 에이전트 토큰에는 email.send가 포함되지 않습니다.

• Management: 도메인, 사서함, 로그, 메트릭, 지출 요약 및 웹훅을 위한 21개 도구. smx_root_* 키가 필요합니다.

• Sending: 첨부 파일 업로드 참조, 단일 발송 및 일괄 발송을 위한 5개 도구. smx_mbx_* 키 또는 소유자 승인 Sending 리소스 smx_agent_* 토큰이 필요합니다.

서버는 시작 전에 잘못된 접두사를 가진 키를 거부합니다.

에이전트를 위한 첨부 파일 워크플로

사용자가 에이전트에게 새 메일을 기다리라고 요청하면 mailbox_wait_for_message를 사용하세요. 이 도구는 제한되어 있습니다. matched=false를 반환하면 MCP 도구 호출을 무기한 열어 두지 말고 다시 호출하세요.

메시지에 첨부 파일이 있는 경우:

1. 첨부 파일 내용이 필요하면 message_id 및 attachment_id와 함께 mailbox_read_attachment를 호출하세요.

2. 작은 텍스트 유사 첨부 파일의 경우 반환된 text를 읽으세요.

3. 이진 또는 대용량 첨부 파일의 경우 반환된 resource_link / download_url을 모델 컨텍스트 밖에서 즉시 사용하세요.

4. 메타데이터로 충분하거나 링크를 새로 고쳐야 할 때만 mailbox_get_attachment를 사용하세요.

MCP를 통한 아웃바운드 첨부 파일에는 mailbox_upload_attachment를 사용하세요. 정확히 하나의 입력 모드를 허용합니다:

• 파일이 클라이언트가 선언한 파일 시스템 루트 내에 있는 경우 로컬 stdio MCP용 file_path.

• 호스팅 MCP 또는 셸 사용 가능 에이전트용 presign_upload_url=true. 정확한 헤더와 API 키 없이 파일을 반환된 URL에 업로드한 다음 반환된 blob_id로 전송하세요.

• content_base64는 디코딩 시 32 KiB로 제한된 아주 작은 에이전트 생성 파일에만 사용하세요. 너무 크면 file_path, 사전 서명 업로드, CLI --attach 또는 SDK 파일 헬퍼로 전환하세요.

file_path 및 사전 서명 업로드 모드는 현재 첨부 파일당 7,500,000 바이트인 사서함 첨부 파일 상한을 사용합니다. 사전 서명 업로드는 또한 정확히 선언된 바이트 길이와 콘텐츠 유형을 고정합니다.

사서함 발송의 경우 mailbox_send_message는 작은 인라인 base64 첨부 파일 객체(content, filename, content_type) 또는 업로드된 첨부 파일 참조(blob_id, filename, content_type)를 허용합니다.

Sending API 발송의 경우 로컬 stdio MCP에서 file_path와 함께 sending_upload_attachment를 호출하거나, 호스팅/셸 사용 가능 에이전트의 경우 sending_create_attachment_upload를 호출하고 모델 컨텍스트 밖에서 바이트를 PUT하세요. 그런 다음 sending_send_email.attachments[]에 {"attachment_id": "att_..."}를 전달하세요. 아주 작은 생성 콘텐츠를 제외하고 Sending 인라인 base64는 피하세요.

콘솔 스크립트

• sendmux-mcp

• sendmux-mcp-mailbox

• sendmux-mcp-management

• sendmux-mcp-sending

• sendmux-mcp-hosted

지원

Sendmux/sendmux-sdk 저장소에 패키지 이름, 버전, 명령, 전송 방식, 그리고 API 오류의 요청 ID를 포함하여 이슈를 열어 주세요.

라이선스

MIT. 라이선스 파일을 참조하세요.