Skip to main content

외부 연동 메뉴 가이드

※ 최종 업데이트: 2025-05-21

sHIELDMail 외부 연동 메뉴에서는 특정 조건에 따라 메일 수신 시 외부 시스템과의 데이터 연동을 설정할 수 있습니다.

이 메뉴를 통해 특정 헤더 값이 포함된 메일을 수신할 경우, 지정된 API로 데이터를 전송할 수 있습니다.

1. 외부 연동 메뉴 진입​

설정 > API 연동 메뉴에서 외부 연동 관리 화면에 접속할 수 있습니다. api

  • 초기 화면에서는 등록된 연동이 없을 경우, 빈 화면이 표시됩니다.
  • API 연동 추가 버튼을 클릭하여 새로운 API 연동 설정을 시작할 수 있습니다.

2. API 연동 등록하기​

API 연동을 추가하려면 API 연동 추가 버튼을 클릭합니다.

  • 연동명 (필수): API 연동을 식별할 이름을 입력합니다.
  • 이벤트 유형 (필수): 현재 지원되는 이벤트 유형은 메일 수신됨입니다.
    • MAIL_RECEIVE: 메일 수신 시 이벤트 트리거
  • 헤더 키 (필수): 이메일 헤더에서 특정 필드를 지정합니다. 예: x-sentmail-sync
  • 헤더 값 (필수): 지정된 헤더 키에 매칭되는 값입니다. 예: yes
  • 대상 URL (필수): API 호출이 이루어질 엔드포인트 URL을 입력합니다.
  • 재시도 설정: API 호출 실패 시 재시도 횟수와 간격을 설정할 수 있습니다.
    • 최대 재시도 횟수: 기본값 3회
    • 재시도 간격 (분): 기본값 1분
  • 활성화 여부: 등록된 API 연동의 활성화 여부를 설정합니다.

설정 완료 후, 저장 버튼을 클릭하여 연동 정보를 저장합니다.

3. API 연동 목록​

API 연동이 등록되면 메인 화면에 연동 목록이 표시됩니다.

  • 연동명, 이벤트 유형, 헤더 키, 헤더 값, 대상 URL, 활성화 상태가 표시됩니다.
  • 각 항목은 클릭하여 편집 또는 삭제할 수 있습니다.

4. 연결 테스트​

API 연동이 등록된 후, 설정이 정상적으로 동작하는지 확인하기 위해 연결 테스트 기능을 제공합니다.

  • 연결 테스트 버튼을 클릭하면 API가 호출되며, 설정된 헤더 키와 값이 전송됩니다.
  • 연결 성공 시: 연결 성공 메시지와 함께 연결 시간 표시
  • 연결 실패 시: 연결 실패 메시지와 오류 상세 정보가 표시됩니다.

5. 주의사항 및 권장사항​

  • 연동명과 대상 URL은 필수 입력 항목입니다.
  • 재시도 설정은 API 서버의 응답 시간에 맞춰 적절히 조정해야 합니다.
  • 헤더 키와 헤더 값은 정확히 일치해야 이벤트가 트리거됩니다.

6. 참고 사항​

  • 현재 MAIL_RECEIVE 이벤트 유형만 지원됩니다.
  • 추가적인 이벤트 유형 (MAIL_SEND, FILE_CONVERT)은 추후 개발 예정입니다.
  • API 호출 시 응답 시간은 10초로 제한됩니다. 초과 시 타임아웃 오류가 발생합니다.

내부 문서 링크​

업데이트 예정입니다.