API와 MCP로 연결된 계정 관리하기

연결된 계정을 사용하면 웹메일 사서함에서 외부 사서함, Gmail, Yahoo, iCloud, Outlook.com/Microsoft 365 또는 모든 IMAP 서버의 메일을 읽고 보낼 수 있습니다. 메시지 API와 MCP 도구는 같은 기능을 프로그래밍 방식으로 제공합니다. 연결된 계정을 나열하고, 추가하고, 테스트하고, 편집하고, 삭제할 수 있으며 일반 메시지 호출(목록, 읽기, 보내기, 플래그, 이동, 삭제, 폴더)을 토큰 자체의 사서함 대신 연결된 계정으로 지정할 수도 있습니다.

쉽게 말하면 mailbox_id는 에이전트가 대신 작업할 수 있는 TrekMail 사서함을 선택하고, external_account_id는 그 안의 Gmail 또는 다른 연결된 사서함을 선택합니다. 두 값은 서로 바꿔 쓸 수 없습니다.

요금제, 한도 및 카탈로그 크기

연결된 계정 관리에는 7개의 메시지 도구가 제공됩니다. 범위가 제한된 토큰에는 전체 제품 카탈로그가 아니라 실제로 사용할 수 있는 도구만 표시됩니다.

시작하기 전에

• 연결된 계정은 웹메일 기능이며 메시지 토큰 인터페이스(/api/v1/messages/...)를 사용합니다. 대시보드 API 토큰이 아니라 아래 범위가 있는 메시지 토큰으로 권한을 부여합니다.
• 요금제 한도는 사서함마다 적용됩니다: Starter 5, Pro 10, Agency 30. Nano 요금제에는 연결된 계정이 포함되지 않습니다.
• 각 endpoint의 범위는 토큰 자체 사서함으로 제한됩니다. 토큰은 자신의 연결된 계정만 보고 관리할 수 있으며 다른 사서함의 계정에는 접근할 수 없습니다.
• 자격 증명과 OAuth 토큰은 응답에서 항상 마스킹됩니다. 비밀번호나 앱 비밀번호를 쓸 수는 있지만 다시 읽을 수는 없습니다.
• Outlook.com 및 Microsoft 365 계정은 웹메일 UI에서 Microsoft 로그인(OAuth)을 통해 연결합니다. API는 연결된 계정을 관리하고 사용할 수 있지만 대화형 Microsoft 동의 단계는 수행하지 않습니다.

범위

메시지 호출에서 연결된 계정을 지정하려면 해당 호출에 원래 필요한 것과 동일한 범위가 필요합니다(예: 메시지 목록에는 messages:read가 필요하고 전송에는 messages:send가 필요합니다).

연결된 계정 관리

기본 경로: /api/v1/messages/external-accounts

계정 추가

POST /api/v1/messages/external-accounts
Scope: messages:write

요청 본문:

먼저 POST /external-accounts/detect를 호출하여 provider와 서버 설정을 자동으로 채우세요. 저장 호출은 저장하기 전에 실제 IMAP + SMTP 테스트를 실행합니다. 422와 오류 범주(auth, tls, network, transient_throttle)가 반환되면 자격 증명이 작동하지 않아 아무것도 저장되지 않았음을 의미합니다.

메시지 호출에서 연결된 계정 지정

사서함에서 작업하는 모든 메시지 endpoint는 선택적 **external_account_id**를 허용합니다. 토큰 자체의 사서함 대신 해당 연결된 계정에서 호출을 실행하려면 이 값을 제공하고, 사서함 자체를 사용하려면 생략하세요. 목록, 읽기, 보내기, 답장, 플래그, 이동, 삭제 및 폴더 목록에 적용됩니다.

GET /api/v1/messages?external_account_id=42&folder=INBOX
Scope: messages:read

POST /api/v1/messages/send
Scope: messages:send
{
  "external_account_id": 42,
  "to": "someone@example.com",
  "subject": "Sent from my connected account",
  "text": "..."
}

external_account_id만 사용해 보내면 해당 계정 자체의 SMTP 서버(제공업체의 SPF/DKIM)를 통해 전송됩니다. 대신 소스에 연결된 identity_id를 제공하면 해당 다른 이름으로 보내기 ID의 도메인 또는 저장된 프로필 경로를 사용하면서도 보낸 편지함 사본은 연결된 받은편지함에 저장합니다. 계정은 정상 상태(status: active)여야 하며, 연결이 끊긴 계정은 다시 연결하라는 오류를 반환합니다. API 및 MCP를 통한 다른 이름으로 보내기 주소를 참조하세요.

MCP 도구

같은 기능을 MCP를 통해 AI 에이전트에서도 사용할 수 있습니다(비공개 stdio 서버와 공개 MCP 서버 모두 지원):

메시지 도구 list_messages, read_message, send_message, list_folders, update_message_flags, move_message, delete_message, prepare_reply, prepare_reply_all, prepare_forward는 선택적 external_account_id 인수를 허용합니다. 보내기, 초안 작성 및 예약에도 소스 연결 identity_id를 사용할 수 있으며 이 값은 list_identities에서 반환됩니다.

관리 도구는 사용자가 제공한 자격 증명을 사용해 임의의 메일 서버로 나가는 연결을 열기 때문에 연결된 계정의 나머지 기능과 동일한 보안 방침을 따릅니다. 여기에는 허용 호스트 목록, 비공개 범위 차단, 허용 포트 목록 및 호스트별 연결 상한이 포함됩니다.