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, namespace, items[];
• authentication.client_auth_mode: app_password_only 또는 password_or_app_password.
• authentication.accepted_passwords: 각각 ["app_password"] 또는 ["mailbox_password", "app_password"].
• authentication.app_passwords_endpoint: 메일함의 앱 비밀번호 관리 엔드포인트.
• 명시적 안전 보장인 password_included: false

shared_mailboxes.items[]는 기본 폴더 접근이 활성화된 경우 읽기 권한이 있는 구성원만 포함합니다. delegated_send_addresses는 id, email, display_name이 있는 사용 가능한 팀 보낸 사람 주소의 별도 목록이며 비어 있을 수 있습니다. 폴더 접근 권한을 주거나 발송 준비를 확인하지 않습니다. 이 주소는 Message API 발신 주소가 아닙니다. White Label에서도 플랫폼 서버 이름을 복사하지 말고 반환된 서버를 사용하세요.

각 위임 항목에는 지속되는 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 폴더 목록은 공유 받은편지함을 읽을 수 있는 사람의 기본 메일 앱 접근을 설명합니다. 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은 설치 중 비밀번호를 요청합니다. app_password_only에서는 앱 비밀번호를 사용하고, password_or_app_password에서는 허용되는 두 비밀번호 중 하나를 사용합니다. 발신 메일을 사용할 수 없을 때 TrekMail은 잘못된 프로파일을 생성하지 않고 409 mail_client_setup_not_ready를 반환합니다.

웹메일의 설정, 앱 비밀번호 또는 대시보드의 메일함, 해당 메일함, 보안, 앱 비밀번호에서 만드세요. 읽기 전용 설정 엔드포인트에서는 만들 수 없습니다. 이 비밀번호와 로그인 방식을 관리하는 REST 엔드포인트 및 MCP 도구는 API와 MCP로 메일 앱 비밀번호 관리하기를 참조하세요.

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.