API 및 MCP를 통한 메일 클라이언트 설정

TrekMail은 대시보드의 앱 및 기기에서 사용하는 것과 같은 연결 데이터를 REST와 MCP로 제공합니다. 두 인터페이스 모두 읽기 전용이며 사서함 읽기 권한이 필요합니다.

사서함 비밀번호나 맞춤 SMTP 공급자의 자격 증명은 절대 반환하지 않습니다. 사용자가 메일 앱에 비밀번호를 직접 입력합니다. 도메인이 맞춤 공급자를 통해 발신 메일을 라우팅하더라도 외부 앱은 TrekMail의 공개 SMTP endpoint로 제출하며, TrekMail이 내부에서 비공개 도메인 경로를 적용합니다.

연결 설정 가져오기

GET /api/v1/mailboxes/{mailbox_id}/client-setup?lang=en
Authorization: Bearer tm_live_...

필수 내부 범위는 mailboxes:read입니다. 토큰의 선택적 domain_ids 및 mailbox_ids 제한도 적용됩니다.

응답에는 다음이 포함됩니다.

• 수신 IMAP 호스트, SSL 포트, 사용자 이름 및 준비 상태
• 발신 SMTP 호스트, SSL 포트, 사용자 이름 및 준비 상태
• 캘린더와 연락처용 DAV 서버 URL, 연결 준비 상태 및 반환 주소의 브랜드 적용 여부
• 앱 및 기기에 표시되는 Gmail, Outlook, Apple Mail, Thunderbird 및 일반 IMAP용 현지화된 3단계 가이드
• sending.mode: platform, profile 또는 not_configured
• sending.reason: 발신 메일이 준비되지 않았을 때의 안정적인 기계 판독 가능 이유
• apple_mail_profile.available: 수신과 발신이 모두 준비된 경우에만 true
• shared_mailboxes.native_access_enabled, 구성된 네임스페이스 및 이 일반 사서함에 위임된 공유 사서함마다 하나의 items[] 항목
• 명시적 안전 보장인 password_included: false

각 위임 항목에는 지속되는 native_access_status/native_access_ready, folders 아래의 정확한 표준 경로, 서버에서 강제하는 operations, 실제 send_as_ready/send_as_reason이 포함됩니다. can_send는 관리자가 할당한 답장 가능 권한이며 SMTP를 사용할 수 없어도 true일 수 있으므로 자동화는 두 준비 상태 필드를 확인해야 합니다. 구성원 사서함이 비활성 상태이거나 로그인이 일시 중지되었거나 직접 로그인이 비활성화되어도 공유 사서함은 표시되지만 보내는 사람 이유로 mailbox_unavailable, mailbox_login_suspended 또는 direct_login_unavailable을 반환합니다. 기존 folder 필드는 정확한 받은 편지함 경로를 유지합니다. 사용자를 안내하기 전에 native_access_ready=true를 기다리세요.

SMTP는 답장이나 전달 메일을 전송하지만 보낸 편지함 사본은 저장하지 않습니다. 따라서 sent_copy.smtp_saves_copy는 false입니다. 팀 전체가 볼 수 있도록 클라이언트에서 사본을 sent_copy.folder(folders.sent와 같은 값)에 추가하게 설정하세요. 클라이언트가 보관 또는 스팸을 자동으로 매핑하지 않을 때 folders.archive와 folders.junk가 정확한 이동 대상입니다. 정크로 이동하는 것만으로 서버 스팸 분류기의 학습이 보장되지는 않습니다.

항상 일반 구성원 사서함 ID로 이 endpoint를 요청하고 해당 구성원의 주소와 비밀번호로 클라이언트를 인증하세요. 두 번째 계정을 만들거나 공유 주소로 직접 인증하지 마세요.

기본 액세스가 비활성화되면 shared_mailboxes.native_access_enabled는 false이고 items는 비어 있습니다. 활성화되어 있지만 items가 비어 있으면 일반 사서함에 현재 활성 공유 사서함 멤버십이 없습니다. 어느 경우에도 비밀번호는 포함되지 않습니다.

선택적 lang 매개변수는 Apple 프로파일 endpoint와 같은 13개 언어를 허용합니다. 생략하면 TrekMail은 Accept-Language를 사용한 다음 기본 로케일을 사용합니다. 각 가이드에는 안정적인 id, 현지화된 세 개의 steps 및 action인 use_server_settings 또는 download_apple_profile이 있습니다.

connection_status=receiving_only는 완전한 설정 성공이 아닙니다. 두 서버를 모두 검증하는 클라이언트 연결을 안내하기 전에 도메인의 발신 경로를 구성하거나 복구하세요.

connection_status=unavailable은 사서함 수명 주기가 변경되어 직접 인증할 수 없음을 뜻합니다. 반환된 서버 정보를 사용하거나 Apple Mail 프로파일을 제공하지 말고 사서함 상태를 새로 고치세요.

Apple Mail 프로파일 다운로드

GET /api/v1/mailboxes/{mailbox_id}/apple-mail-profile?lang=en
Authorization: Bearer tm_live_...
Accept: application/x-apple-aspen-config

응답은 .mobileconfig 첨부 파일입니다. 지원되는 lang 값은 en, es, fr, de, pt, it, nl, ru, zh, ja, ko, ar, he입니다. lang을 생략하면 TrekMail은 Accept-Language와 기본 로케일을 차례로 사용합니다.

프로파일에는 IMAP 및 SMTP 설정이 있지만 비밀번호 필드는 없습니다. Apple은 설치 중 사용자에게 사서함 비밀번호를 요청합니다. 발신 메일을 사용할 수 없을 때 TrekMail은 잘못된 프로파일을 생성하지 않고 409 mail_client_setup_not_ready를 반환합니다.

MCP 도구

도구는 같은 REST endpoints와 권한 부여 규칙을 사용합니다.

MCP 전송은 브라우저 다운로드 대신 구조화된 도구 콘텐츠를 반환합니다. content_base64를 바이트로 디코딩하여 file_name으로 저장하세요. 디코딩 전에 JSON이나 UTF-8로 해석하지 마세요.

두 도구 모두 내부 mailboxes:read로 확장되는 호스팅 OAuth 범위 mail:read가 필요합니다. 읽기 전용이며 자체 호스팅 stdio 서버의 파괴적 작업 환경 플래그에 의존하지 않습니다.

오류

설정 endpoint는 다음 sending.reason 값을 반환할 수 있습니다: mailbox_unavailable, direct_login_unavailable, domain_unavailable, domain_deprovisioning, account_suspended, email_verification_required, mailbox_sending_disabled, smtp_not_configured, managed_smtp_not_in_plan, managed_smtp_entitlement_inactive, smtp_profile_unavailable, smtp_route_invalid.