HTTP API 참조

언어 및 오류 코드

영어가 기본값입니다. API, 웹 콘솔 및 알림 렌더러는 internal/i18n/locales/에 포함된 카탈로그를 공유합니다. internal/i18n/languages.json는 다음과 같은 표준 코드와 기본 이름을 정의합니다.

• 처음 방문할 때 콘솔은 브라우저의 Accept-Language 를 사용합니다. 선택기는 선택한 표준 코드를 로컬에 저장합니다. 콘솔 언어를 전환하면 저장된 알림 설정이 변경되지 않습니다.
• 앱 관리 요청을 포함한 API 요청은 품질 가중치에 따라 Accept-Language를 협상합니다. 응답에는 Content-Language 및 Vary: Accept-Language 가 포함됩니다. 지원되지 않는 기본 설정은 건너뜁니다. 누락되었거나 유효하지 않거나 완전히 지원되지 않는 기본 설정은 en로 대체됩니다. 가중치가 0인 언어는 협상에서 제외됩니다.
• 지역 변형은 지원되는 언어로 매핑됩니다: fr-CA → fr , es-MX → es , pt / pt-PT → pt-BR . 중국어 스크립트가 존중됩니다: zh-Hans / zh-CN / zh-SG → zh-CN ; zh-Hant / zh-TW / zh-HK / zh-MO → zh-Hant . 명시적인 스크립트는 지역보다 우선합니다. 일반 zh는 중국어 간체를 사용합니다.
• GET /locales/default.json는 협상된 카탈로그를 제공합니다. GET /locales/{canonical-code}.json는 해당 카탈로그를 명시적으로 제공합니다. 알 수 없는 카탈로그 경로는 locale_not_supported 를 반환합니다.
• 전달 설정 language는 요청 또는 콘솔 언어와 관계없이 아웃포스트에서 생성된 알림을 제어합니다. 이는 표준 코드와 지원되는 지역 변형을 허용하고, 표준 코드를 유지하며, 생략되거나 비어 있는 경우 기본값은 en입니다. 지원되지 않는 명시적 값은 400 config_language_invalid 를 반환합니다.
• 푸시 전송 서비스는 페어링된 장치의 언어를 사용하여 네이티브 테스트 알림 텍스트를 생성합니다. 아웃포스트 알림 언어는 해당 언어를 재정의하지 않습니다. 푸시 전달 서비스와 앱은 각각 자체 언어 세트를 지원합니다.
• 표준 폴더 역할과 공통 폴더 이름은 콘솔에서 현지화됩니다. 원시 IMAP 경로, 사용자 정의 이름 및 folder_roles는 API에서 변경되지 않습니다. 앱은 자체 카탈로그를 사용하여 이러한 역할을 현지화합니다. 알림 제목은 원래 리프 폴더 이름을 계속 사용합니다. 사용자가 입력한 이름, 이메일 제목, 이메일 내용 및 확인 코드는 그대로 유지됩니다.
• 로그 및 CLI 출력은 영어를 사용합니다. 비즈니스 오류는 안정적인 영어 snake_case 코드와 명명된 매개변수를 유지합니다. 스토리지는 코드와 매개변수를 유지하고 디스플레이 레이어는 메시지를 번역합니다. API 응답의 날짜와 숫자는 기계가 읽을 수 있는 기존 형식을 유지합니다. 콘솔은 선택한 로케일을 사용하여 타임스탬프 형식을 지정합니다.

{
  "error": {
    "code": "unauthorized",
    "message": "Sign in with a valid session or API token."
  }
}

배달 기록의 last_error 및 폴더 상태의 notice는 동일한 {code, message, params?} 모양을 사용합니다(예: bark_http_error 와 {"status":"503"} ). code의 분기; message를 보여주세요.

각 사서함은 폴더 검색 및 연결 테스트를 위해 하나의 연결을 예약합니다. 감시자 수요는 realtime Folder count + (1 if any scheduled Folders exist, otherwise 0) 이며, 최대 connection_limit - 1 연결(기본적으로 9개)입니다. 해당 사서함에 대한 모든 작업은 함께 connection_limit(2–100) 내에 유지됩니다. configuration_invalid를 사용하여 복구 모드에서 1번의 시작으로 제한되는 구성이 저장되었습니다.

HTTP API

GET /는 현재 페이지를 제공합니다. 정적 자산 및 /healthz는 공개됩니다. 설정하기 전에 다른 모든 관리 엔드포인트는 403 setup_required 를 반환합니다. POST /api/v1/setup는 한 번만 사용할 수 있습니다. POST /api/v1/session는 설정 후 공개됩니다. 나머지 모든 API에는 세션 쿠키 또는 Authorization: Bearer mwk_… 가 필요합니다.

쿠키 세션은 TLS 연결 또는 HTTPS 원본에서 HttpOnly, SameSite=Strict, Path=/, Secure, 7일 유휴 시간 제한 및 30일 절대 시간 제한을 사용합니다. 모든 쿠키 인증 변이에는 X-CSRF-Token 및 호스트와 선택적 포트가 요청 호스트와 정확히 일치하는 HTTP(S) Origin가 필요합니다. 베어러 요청은 CSRF 확인을 건너뜁니다. 유효한 쿠키가 있는 경우에도 잘못된 Authorization 헤더가 실패합니다.

로그인 및 설정 코드 실패는 소스-주소 예산을 공유합니다. 즉, 15분당 10번의 실패, 그 다음 초 단위로 429 too_many_attempts 및 Retry-After가 이어집니다. 소스는 위의 신뢰할 수 있는 프록시 범위를 사용하는 Gin ClientIP입니다. 비밀번호 변경에도 이 예산이 사용됩니다. 명시적인 교차 사이트 원본은 로그인 및 설정 시 거부됩니다. 모든 개인 네트워크 피어는 프록시로 신뢰되기 때문에 로컬 네트워크의 클라이언트는 X-Forwarded-For를 설정하고 해당 시도를 여러 소스 주소에 분산시킬 수 있습니다. 아웃포스트 수신기를 신뢰할 수 없는 로컬 네트워크에 노출하지 마십시오. 역방향 프록시를 통해서만 게시하세요.

모든 JSON 본문은 64KiB로 제한됩니다. 알 수 없는 필드 또는 후행 JSON은 400을 반환합니다. 비밀번호는 최소 12자, 최대 1024UTF-8바이트입니다. 사용자 이름과 토큰 이름은 1~128바이트입니다. 모든 관리 API 타임스탬프는 배달 created_at / accepted_at , 토큰 created_at / last_used_at , 폴더 확인, 로그 시간 및 진단 생성 시간을 포함하여 UTC의 RFC 3339 문자열입니다. 분수 초는 저장된 정밀도를 유지합니다. 사용되지 않은 토큰 last_used_at는 null입니다. 승인 없이 배송되는 경우 accepted_at를 생략하세요. 개수, 기간 및 개정판은 숫자로 유지됩니다.

401은 잘못된 세션이나 API 토큰을 식별하거나 POST /api/v1/session에서 거부된 자격 증명을 식별합니다. 잘못된 설정 코드는 400 setup_code_invalid 를 반환합니다. 마법사는 코드 단계로 돌아가서 사용자 이름을 유지합니다. PUT /api/v1/admin/password의 잘못된 현재 비밀번호는 400 current_password_invalid를 반환하고 실패 제한에 포함됩니다. 현재 세션은 유효하게 유지됩니다. 로그인 실패 및 현재 비밀번호 오류는 입력 내용을 유지하면서 양식 내에 표시됩니다.

전송 레코드에는 선택적인 message 개체인 mailbox_id , mailbox_label , folder , subject(문자열 또는 null) 및 test(부울)이 포함됩니다. 이름은 대기열에 추가된 시간의 스냅샷이며 사서함 이름을 바꾸거나 삭제해도 유지됩니다. null 제목은 해당 제목이 보관되지 않았음을 의미합니다. 빈 문자열은 메일에 제목이 없다는 의미입니다. 테스트 알림에는 test=true가 있고 사서함 소스는 없습니다. API는 이 요약에서 보낸 사람과 본문을 생략합니다.

사서함 생성 예:

{
  "label": "Work mailbox",
  "host": "imap.example.org",
  "port": 993,
  "username": "user@example.org",
  "password": "…",
  "connection_limit": 10
}

아웃포스트에는 수리 대기 중인 잘못된 구성을 포함하여 최대 20개의 저장된 사서함이 허용됩니다. 다음 생성은 400 mailbox_limit_exceeded 를 반환합니다. ID는 mbx_와 임의 문자열로 생성되며 안정적으로 유지됩니다. label는 기본적으로 사용자 이름(이메일 주소)을 사용하며 최대 64개의 유니코드 문자를 허용하고 줄 바꿈을 거부합니다. 64자를 초과하는 사용자 이름에는 명시적으로 더 짧은 라벨이 필요합니다. 업데이트 시 생략된 레이블은 저장된 값을 유지합니다. 빈 라벨은 제출된 사용자 이름을 사용합니다.

Mailbox PUT는 동일한 형식과 "revision":1(GET에서 읽은 값)를 사용하며 호스트, 포트 및 사용자 이름이 필요합니다. 호스트, 포트, 사용자 이름이 같으면 생략한 비밀번호는 저장된 값을 유지합니다. 명시적으로 비어 있는 비밀번호는 거부됩니다. 생략됨 connection_limit는 현재 값을 유지합니다. 새 사서함의 기본값은 10이며 범위는 2~100입니다. POST 생성은 개정을 생략하거나 0을 보냅니다. 테스트 경로는 개정을 요구하지 않고 동일한 필드를 수락하고 구성을 변경하지 않고 유지합니다. 저장되지 않은 테스트에는 자격 증명이 필요합니다. 저장된 메일함 테스트는 지정된 ID에서 생략된 자격 증명만 병합합니다.

사서함 GET 보기에는 id , label , revision , host , port , username , connection_limit , connections_in_use 및 "password":{"configured":true} . 복구된 유효하지 않은 사서함은 configured:false를 보고하고 해당 ID와 수정본을 유지하여 복구할 수 있습니다. GET 비밀번호 개체는 유효한 쓰기 값이 아닌 보기입니다.

각 사서함에는 독립적인 연결 예산이 있습니다. 실시간 폴더는 각각 하나의 슬롯을 사용합니다. 예약된 모든 폴더는 함께 하나를 소비합니다. 이들의 결합된 수요는 connection_limit - 1 내에 맞아야 하며 관리를 위해 하나의 슬롯을 예약해야 합니다. 구독 PUT 및 메일함 제한 변경으로 인해 이 공식이 적용됩니다. 소진된 용량은 connection_budget_exceeded 를 반환합니다. 저장되지 않은 사서함을 테스트하면 임시 예산이 사용됩니다. 저장되지 않은 테스트, 저장된 사서함 테스트 및 폴더 검색 끝점은 추가로 전역 동시성 제한 2를 공유합니다. 초과 요청은 즉시 429 discovery_busy를 반환합니다. 완료하거나 취소하면 동시 실행 슬롯이 해제됩니다.

초기에 구성되지 않은 채널에 대한 전달 PUT 예:

{
  "revision": 0,
  "channel": "bark",
  "preview": "off",
  "retry_count": 0,
  "language": "en",
  "bark": { "endpoint": "https://api.day.app", "key": "…" }
}

각 업데이트 전에 /settings/delivery를 읽고 개정판을 보내십시오. 첫 번째 저장은 0에서 1로 진행됩니다. Pushover는 "pushover":{"token":"…","user":"…"}를 사용합니다. 웹훅은 "webhook":{"url":"https://hooks.example.org/mail","secret":"…"} 를 사용합니다. 채널, 미리보기, 수정이 필요합니다. 생략된 언어 및 재시도 횟수는 기본값을 사용합니다. 대상이 같으면 Webhook URL을 포함한 자격 증명을 생략할 때 저장된 값이 유지됩니다. 명시적으로 비어 있는 활성 자격 증명은 거부됩니다. GET는 모든 자격 증명을 {"configured":true|false}로 대체합니다. 별도의 테스트 엔드포인트는 수정이 필요하지 않습니다.

메일함 생성 및 연결 변경은 저장하기 전에 연결/로그인을 테스트합니다. 호스트, 포트, 사용자 이름 및 연결 제한 (connection_limit)이 저장된 값과 일치하고 비밀번호가 생략된 경우 PUT는 레이블만 변경합니다. 개정 확인 및 지속성은 계속 적용되며 테스트 및 감시자 교체는 건너뜁니다. 대기 중인 작업은 원래 레이블을 유지합니다. 향후 작업에서는 새 레이블을 사용합니다. 다른 사서함에서 이미 사용하고 있는 ID를 만들거나 업데이트하면 409 mailbox_duplicate가 반환됩니다(호스트와 사용자 이름은 대소문자를 구분하지 않고 포트를 정확하게 비교합니다). 동시 생성은 해당 ID를 한 번만 저장할 수 있습니다. 알림 설정 PUT는 테스트를 보내거나 공급자에게 연락하지 않고도 필드, 주소, 선택한 페어링 상태 및 개정 검증 후 모든 채널을 저장합니다. 명시적 전달 테스트는 저장된 설정을 변경하지 않고 그대로 둡니다. 실패로 인해 이후 저장이 차단되지 않습니다. 메일박스 테스트는 구성 잠금 외부에서 실행되며 기존 감시자를 활성 상태로 유지합니다. 실패한 사서함 테스트는 이전 구성을 유지합니다. 오래된 설정 개정은 409 settings_conflict를 반환합니다. 사서함 테스트 중에 구독이 변경되면 해당 테스트의 스냅샷도 무효화됩니다. 다시 시도하기 전에 새로고침하세요. 각 사서함과 전체 배달 설정에는 독립적인 개정이 있으므로 다른 사서함이나 사서함에 대한 편집 내용과 배달이 충돌하지 않습니다.

성공적인 PUT는 민감 정보를 제거한 응답를 반환하고 즉시 적용됩니다. 사서함 연결 변경은 저장 및 선택적 커서 재설정 전에 자체 감시자를 중지합니다. 저장에 실패하면 복원됩니다. 다른 사서함은 계속 실행됩니다. 전송 변경 사항은 진행 중인 시도의 스냅샷을 보존합니다. 후속 시도에서는 새 것을 사용합니다. 보류 중인 작업은 전달이 구성 해제되는 동안 기다립니다.

GET /api/v1/mailboxes/:id/subscriptions 는 {"revision":1,"folders":[{"name":"INBOX","check":"realtime"},{"name":"Clients","check":"5m"}]} 를 반환합니다. PUT는 개정 읽기와 전체 folders 어레이를 보냅니다. 빈 배열은 모든 것을 구독 취소합니다. 이름은 각 사서함 내에서 고유하고 INBOX는 정규화되며 각 이름은 최대 4096UTF-8바이트입니다. 모든 폴더에는 name 및 check가 필요합니다. 검사 방식은 realtime , 5m 또는 15m 입니다. 누락/잘못된 검사 및 이전 문자열 배열 형식은 400을 반환합니다. 위의 연결 요구 공식은 폴더 수 제한을 대체합니다. 확인만 변경하면 진행 상황이 유지되고 새 메일을 따라잡으며 기존 이벤트 ID가 유지됩니다. 취소하고 나중에 다시 구독하면 새로운 기준이 구축됩니다. 모든 필드가 필수입니다. 저장하면 다음 개정판에서 202가 반환됩니다. 오래된 개정판은 409 subscriptions_conflict 를 반환합니다. 폴더 존재는 감시자에 의해 확인되므로 사서함이 오프라인인 동안 구독을 제거할 수 있습니다. 스토리지 오류는 503을 반환하고 현재 구독을 유지합니다.

모든 /status.folders[] 항목에는 mailbox_id , mailbox_label 및 check 가 포함됩니다. mode 는 idle , poll 또는 scheduled 입니다. 예약된 폴더에는 next_check(RFC 3339 시간, 재시도 시간 포함)도 포함됩니다. 실시간 폴더에는 next_check 가 생략됩니다. JSON 또는 모델 검증에 실패한 저장된 구성은 mailbox:<id> 또는 delivery 아래의 /status.notices에서 configuration_invalid를 사용하여 구성 해제됩니다. PUT가 해당 항목을 수리합니다. 초과 구독은 해당 사서함만 일시 중지하고 subscriptions:<id> 아래에 connection_budget_exceeded를 보고합니다. 구독을 줄이거나 한도를 늘리면 모니터링이 재개됩니다. 암호 복호화에 실패하면 시작이 중지됩니다.

진단 허용 목록에는 check 및 mode를 포함하여 생성 시간, 빌드/이동/플랫폼 정보, 대기열 수, 익명 사서함 및 감시자 상태가 포함됩니다. mailboxes[].index 및 watches[].mailbox_index는 해당 보고서 내에서 "Mailbox 1", "Mailbox 2" 등을 식별합니다. 각 사서함의 감시자에는 자체 index가 있습니다. 사서함 항목에는 구성/구독 알림 코드가 포함됩니다. imap_folder_rejected만 watches[].response_code를 포함할 수 있습니다. 보고서에는 사서함 ID, 표시 이름, 주소, 서버 이름, 폴더 이름, 메시지 데이터, 작업 ID, 자격 증명 및 기타 모든 오류 매개 변수가 생략되어 있습니다.

작업 상태: pending는 요청을 기다리고, accepted는 채널이 요청을 수락했음을 의미하고, dead는 기록된 실패로 시도가 종료되었음을 의미합니다.

런타임 로그

JSON stderr 출력에는 docker compose logs -f core (또는 docker logs <container> )를 사용하세요. 인증된 클라이언트는 GET /api/v1/logs?after=0&level=info&mailbox_id=mbx_example&limit=200를 통해 동일한 운영 이벤트를 쿼리할 수 있습니다. 세션 쿠키 또는 API 토큰이 필요합니다.

인메모리 링은 최신 2000 정보/경고/오류 항목을 유지하고 다시 시작하면 지워집니다. after는 해당 값 자체를 제외하는 음이 아닌 시퀀스 기준값입니다. level는 해당 레벨 이상을 선택합니다(info 기본값). 생략됨 mailbox_id에는 모든 사서함과 전역 작업이 포함됩니다. limit의 기본값은 200이고 범위는 1~500입니다. 잘못된 매개변수는 400 logs_request_invalid 를 반환합니다.

{
  "entries": [
    {
      "seq": 42,
      "time": "2026-09-29T00:00:00Z",
      "level": "info",
      "message": "Folder connection established",
      "attrs": {
        "mailbox_id": "mbx_example",
        "folder": "INBOX",
        "mode": "idle",
        "check": "realtime"
      }
    }
  ],
  "next": 42,
  "cleared_through": 0
}

다음 요청의 after로 next를 사용하세요. 페이지 제한에서는 마지막으로 반환된 시퀀스입니다. 스냅샷을 스캔한 후 필터가 일치하는 항목이 없는 경우를 포함하여 스냅샷 꼬리로 이동합니다. 제거된 항목은 건너뜁니다. 재시작이 next < after 를 반환하면 커서를 0으로 재설정합니다. 항목은 순서대로 정렬됩니다.

로그에는 사서함 및 폴더 수명주기, 기준/대기열에 추가 횟수, 배달 시도, 구성 변경 및 관리자 작업이 포함됩니다. 글로벌 이벤트는 빈 mailbox_id 를 사용합니다. 다음 스칼라 속성만 노출됩니다: mailbox_id , folder , mode , check , code , event_id , channel , attempt , duration_ms , http_status , next_attempt , backoff_seconds , count , revision , token_id , version , listen . http_status=0는 HTTP 응답이 수신되지 않았음을 의미합니다. token_id는 토큰 값이 아닌 공개 기록 식별자입니다. 비밀번호, 토큰/세션 값, 설정 코드, 보낸 사람, 제목, 본문 및 자격 증명 URL은 생략됩니다. setup-code 줄은 콘솔로만 이동합니다. 로그에는 폴더 이름이 포함됩니다. 익명 진단 내보내기에서는 로그와 이름이 제외됩니다.

폴더 검색 및 관리자 메일함 테스트에서는 folders 를 원래 경로 배열과 선택적인 folder_roles , 경로에서 inbox , drafts , sent , trash , junk , archive 로의 맵으로 반환합니다. all 또는 flagged . 역할은 IMAP SPECIAL-USE 속성에서 나옵니다. INBOX는 프로토콜 정의 이름으로 인식됩니다. 웹 UI는 역할이 없는 경우 일반적인 영어 폴더 이름에 대해 대소문자를 구분하지 않고 정확히 일치하도록 대체합니다. 번역된 이름은 괄호 안에 원래 경로를 표시합니다. 다른 이름은 변경되지 않습니다. 디스플레이 번역은 구독 경로를 변경하지 않습니다. 알림 제목은 슬래시로 구분된 폴더 경로의 마지막 세그먼트를 사용합니다. 구조화된 폴더 필드는 전체 경로를 유지합니다. 앱 사서함 테스트는 계속해서 연결 상태만 반환합니다.

GET /api/v1/session에는 인증된 쿠키 세션을 위한 username가 포함되어 있습니다. 토큰 인증은 기존 응답을 유지합니다.

앱 수신 장치

배송 설정에는 native_pairing_id가 포함됩니다. native 채널의 경우 /api/v1/native/devices에서 활성 페어링 하나를 선택합니다. 테스트 알림과 새 이벤트 모두 해당 페어링만 대상으로 합니다. 업데이트 시 필드를 생략하면 저장된 선택이 유지됩니다. 빈 선택은 native_target_required 를 반환합니다. 사용할 수 없는 선택 항목은 native_target_unavailable 를 반환합니다. 선택한 네이티브 페어링을 취소하면 채널과 Native_pairing_id가 원자적으로 지워지고 수정 버전이 한 번 증가합니다. 다른 대상과 채널은 그대로 유지됩니다. 기존 전달은 대상 및 취소 결과를 유지합니다. 타이밍, 동시성 및 재시작 동작은 페어링 동기화를 참조하세요.

앱 승인은 관리 및 푸시 권한을 독립적으로 관리합니다. 두 권한 중 하나를 취소하면 다른 권한은 변경되지 않습니다.

네이티브 테스트 알림

아웃포스트는 {pairing_id,test_id}(명시적 테스트에 따른 새로운 UUID)와 함께 서명된 POST /v1/pairing-tests를 사용합니다. 푸시 전달 서비스는 고정 컨텐츠를 생성하여 Native Push 권한을 요구하지 않고 이를 APNs에 동기적으로 제출합니다. 양식 테스트, 앱 저장 설정 테스트 및 /api/v1/test-push는 이와 동일한 경로를 사용합니다. 테스트는 메일 보낼 편지함과 별개이며 자동 전송 재시도가 없습니다.

아웃포스트는 푸시 전달 서비스가 accepted 를 보고하는 경우에만 HTTP 204를 반환합니다. APNs 거부, 알 수 없는 결과 및 sending가 현지화된 오류를 반환합니다. 푸시 전달 서비스 속도 제한으로 인해 아웃포스트가 Retry-After를 사용하여 HTTP 429를 반환하게 됩니다. 안전한 로그에는 응답 본문, 토큰 및 알림 내용을 제외한 푸시 전달 서비스 HTTP 상태 및 안정적인 오류 코드가 포함됩니다. 아웃포스트와 앱은 푸시 전달 서비스의 기존 장치별 분당 및 대상별 일일 할당량과 (device_id,test_id) 멱등성을 공유합니다. 다른 테스트를 시작하는 사용자는 새 테스트 ID를 생성합니다.

공식 메일은 /v1/push를 사용하며 이벤트 ID나 클라이언트 테스트 플래그에 관계없이 자격 부여 상태를 유지합니다. 이 아웃포스트 버전 이전에 푸시 전달 서비스 페어링 테스트 경로를 배포합니다. 아웃포스트는 유료 메일 배달로 돌아가지 않습니다.

전송 기록 및 런타임 로그 지우기

• DELETE /api/v1/deliveries 는 200 {"deleted":N} 를 반환합니다. 연관된 기본 레코드를 포함하여 전체 기록에서 완료된 레코드( accepted / dead )를 영구적으로 제거합니다. 보류 중인 배달/재시도, 여전히 보류 중/대기 중/전송 중이거나 상태 확인이 예정된 기본 레코드 및 보류 중인 기본 활동 업데이트가 유지됩니다. 실패를 지우면 수동 재시도 옵션이 제거됩니다. 사서함 검사점 및 구성이 유지됩니다.
• DELETE /api/v1/logs는 200 {"cleared_through":N}를 반환하고 모든 수준 및 사서함에 대한 공유 메모리 내 링을 지웁니다. 시퀀스 번호는 계속 증가합니다. stderr/container 로그와 내보낸 파일은 그대로 유지됩니다. GET /api/v1/logs는 cleared_through도 반환합니다. 클라이언트는 반환된 항목을 추가하기 전에 seq <= cleared_through를 사용하여 캐시된 항목을 삭제합니다.
• 두 엔드포인트 모두 관리자 세션 + Origin/CSRF 또는 관리자 API 토큰이 필요합니다. 앱 장치 자격 증명은 이러한 작업을 부여하지 않습니다. 반복적인 삭제는 안전합니다. 작업 후에 새 작업 및 로그 항목이 나타날 수 있습니다.

앱 메시지 내용

POST /api/v1/app/content는 기기에 연결된 제어 자격 증명과 소유자가 허용한 content 범위를 사용합니다. { "reference": <message_ref> }를 보내면 text, truncated, 선택적 정제된 html, has_remote_images를 반환합니다. 본문 읽기는 무료입니다.

본문을 읽을 수 있게 된 뒤 같은 자격 증명, 범위 및 참조로 POST /api/v1/app/content/read를 호출하면 메일함의 해당 메일을 읽음으로 표시합니다. 성공 시 204 No Content와 Cache-Control: no-store를 반환합니다. 본문 가져오기만으로는 읽음 상태가 바뀌지 않습니다. 두 작업 모두 현재 권한, 구독 폴더, 메일함 식별 정보와 메일 참조를 검증합니다.

자격 증명과 연결 대상

테스트하거나 저장할 때 host, port, username을 변경하면 저장된 사서함 비밀번호를 다시 입력해야 합니다. 생략하면 400 mailbox_password_required_for_change가 반환됩니다. 저장된 Bark 주소를 변경할 때는 다른 채널을 선택한 상태에서도 기기 키를 다시 입력해야 하며, 생략하면 400 bark_key_required_for_change가 반환됩니다. 포트, 경로, 마지막 슬래시도 주소에 포함됩니다. 거부된 요청은 연결을 시작하지 않고 설정과 revision을 유지합니다.

App 요청 진단

진단 내보내기는 schema_version: 2를 사용하며 공유 메모리 로그 2000개에서 최근 완료된 App 요청을 최대 300개까지 app_requests에 포함합니다. 시간, 서버가 생성한 request_id(X-Request-ID로도 반환), 경로 템플릿, 메서드, HTTP 상태, 소요 시간, 단계, 결과와 안전한 오류 코드를 기록합니다. 리소스 ID, 쿼리 문자열, 자격 증명, 서명된 참조, 본문과 전체 실행 로그는 제외합니다. 재시작이나 로그 삭제 시 기록이 사라지며 다른 로그가 오래된 요청을 밀어낼 수도 있습니다. 다운로드 전에 보고서를 갱신합니다. 서버에 도달하지 않은 요청에는 App 진단이 필요합니다.

POST /api/v1/app/content/read는 UID와 플래그를 조회합니다. 이미 읽은 메일은 성공하며 읽지 않은 메일은 읽음으로 표시한 뒤 다시 확인합니다. STORE OK만으로 존재를 증명할 수 없습니다. UID 없음, UIDVALIDITY 변경 또는 명시적인 폴더 없음은 404, 제공업체나 권한 오류는 503, 시간 초과는 504입니다. 원격 참조가 만료되어도 캐시된 본문은 읽을 수 있습니다.

Markdown · AGPL-3.0-only · Mailwake 기여자