쇼핑몰 주문 알림, 사내 시스템의 고객 공지, 신청 페이지 접수 안내처럼 사람이 매번 화면에 들어가 발송 버튼을 누르기 어려운 업무는 API로 옮기는 편이 안전합니다. 화면 발송은 담당자가 자리를 비우면 멈추지만, API 연동은 정해진 조건에서 같은 결과를 반복합니다.
이 글은 이지센더 개발자 문서에 정리된 실제 요청·응답 구조를 기준으로, 대량·예약 발송을 접수 → 상태 확인 → 결과 수신까지 연결하는 순서를 정리했습니다. 테스트 키로 먼저 연습하고 운영 키로 전환하는 절차, 키를 잃어버렸을 때의 대응, 웹사이트에서 직접 보내는 방식과 API를 나누는 기준까지 함께 다룹니다.

이지센더 제공 이미지에서 고른 사진. 발송 자동화는 화면 조작을 코드로 옮기는 일이 아니라, 접수와 결과 확인을 분리하는 설계입니다.
연동 전에 정해야 하는 세 가지
1. 테스트 환경과 운영 환경을 나눠 씁니다
이지센더의 API 키는 테스트와 운영 두 환경으로 발급됩니다. 테스트 키로 실행한 요청은 실제 구독자나 캠페인을 바꾸지 않고, 메일도 외부 알림도 나가지 않습니다. 응답 형식과 오류 코드를 익히는 단계는 항상 테스트 키로 끝내고, 운영 키는 마지막에 붙이는 것이 원칙입니다.
요청에는 X-Ezsender-Environment 헤더로 test 또는 live를 지정할 수 있습니다. 키의 환경과 헤더 값이 다르면 요청은 실행되지 않습니다. 운영 키를 실수로 테스트 코드에 넣었을 때 실제 발송이 나가는 사고를 막아 주는 장치이므로, 코드에서 환경 값을 상수가 아니라 설정값으로 두는 편이 좋습니다.
2. 요금제에 따라 운영 호출 범위가 다릅니다
테스트 키의 모의 실행은 모든 요금제에서 가능하지만, 운영에서 실제 데이터를 바꾸는 호출은 기능별로 열립니다. 구독자·정보 항목·세그먼트와 기본 자동화, 구독자 변경 알림은 스탠다드 이상, 이메일·그룹·템플릿·첨부파일·성과·뉴스레터 연동과 발송 결과 알림은 프로 이상, 주소록·발신 주소 관리 연동은 엔터프라이즈부터입니다. 발송 작업 접수도 프로 이상에서 운영 호출이 허용됩니다.
3. 키에 필요한 권한만 붙입니다
키를 만들 때 연동 목적(상담·접수 알림, 통계 조회, 주소록 동기화, 메일 발송, 자동화 운영, 뉴스레터 연결, 결과 알림)을 고르면 필요한 세부 권한이 선택됩니다. 목적과 무관한 권한이 함께 켜져 있지 않은지 발급 화면에서 확인하세요. 권한은 나중에 좁힐 수 있지만, 이미 발급된 비밀값은 화면에 다시 표시되지 않습니다.

모든 요청에 공통으로 붙는 것
API의 기본 주소는 https://ezsender.net/api/v1이고, 인증은 두 개의 헤더로 합니다. X-EZSENDER-ID는 키의 식별자, X-EZSENDER-SECRET은 비밀값입니다. 비밀값은 서버의 환경 변수나 시크릿 저장소에 두고, 브라우저에서 실행되는 코드나 저장소에 커밋되는 파일에는 넣지 않습니다.
응답 헤더에는 추적에 쓰는 값이 함께 옵니다. X-Request-Id는 문의할 때 알려 주면 해당 요청을 바로 찾을 수 있는 번호이고, X-RateLimit-Limit·X-RateLimit-Remaining·X-RateLimit-Reset은 호출 한도와 남은 횟수, 다음 집계 구간 시각입니다. 한도를 넘으면 429가 오고 Retry-After에 기다릴 초가 담깁니다. 재시도는 그 값만큼 기다린 뒤 하는 것이 맞고, 즉시 반복하면 같은 429를 다시 받습니다.
대량·예약 발송 흐름: 캠페인과 발송 작업은 다릅니다
가장 많이 헷갈리는 지점입니다. 캠페인은 보낼 내용과 받을 사람의 정의이고, 발송 작업(send-jobs)은 그 캠페인을 실제로 언제 보낼지 정한 실행 단위입니다. 캠페인 하나로 예약을 여러 번 만들 수 있고, 반대로 예약을 취소해도 캠페인은 남습니다.
단계 | 호출 | 하는 일 |
|---|---|---|
1 |
| 제목·본문·발신 정보로 캠페인 생성(초안) |
2 |
| 즉시 또는 예약 발송 접수, 202와 함께 작업 ID 반환 |
3 |
| 예약 시각·상태·성공/실패 수 확인 |
4 |
| 시작 전 예약 취소 |
5 |
| 발송 완료·실패 알림의 전달 결과 확인 |
즉시 발송과 예약 발송
접수 본문의 mode에 immediate 또는 scheduled를 넣습니다. 예약은 scheduledAt이 필수이고, 미래 시각이어야 하며 시간대를 포함한 ISO 8601 형식(2026-12-01T09:00:00+09:00 또는 Z)으로 보냅니다. 시간대를 생략하면 서버가 어느 시각으로 해석할지 보장되지 않으니, 서버 시간이 UTC여도 고객이 보는 시각은 +09:00으로 명시하는 편이 안전합니다.
접수에 성공하면 202와 함께 sendJob 객체가 옵니다. 여기서 확인할 값은 id(작업 ID), status, scheduledAt, recipientCount(접수 시점의 대상 인원)입니다. 202는 “발송을 시작할 수 있게 접수했다”는 뜻이고, 메일이 나갔다는 뜻은 아닙니다. 완료 여부는 상태 조회나 웹훅으로 확인합니다.
상태 값과 취소, 시각 변경
작업 상태는 scheduled, sending, completed, failed, cancelled로 구분됩니다. 예약 취소는 아직 발송 처리가 시작되지 않은 scheduled 상태에서만 됩니다. 취소는 되돌릴 수 없고, 취소한 작업을 다시 보내려면 새 작업을 접수해야 합니다. 대상과 내용은 그대로 두고 시각만 옮기려면 POST /send-jobs/{id}/reschedule에 새 scheduledAt을 보냅니다. 이 호출은 프로 이상에서 운영 가능합니다.
재시도해도 두 번 발송되지 않게
발송 접수에는 Idempotency-Key 헤더가 필수입니다. 네트워크 오류로 응답을 받지 못해 같은 요청을 다시 보낼 때, 같은 키를 유지하면 서버가 중복 접수로 처리합니다. 다른 요청에 같은 키를 재사용하면 409가 옵니다. 주문번호나 신청번호처럼 업무적으로 유일한 값을 쓰면 재시도 로직을 따로 만들지 않아도 됩니다.

이지센더 계정 설정의 API 연동 화면. 연결·실행 확인에서 키를 고르고 요청을 실행하며, 실행 결과와 호출 기록을 같은 화면에서 확인합니다.
웹훅으로 결과를 받는 구조
발송 결과는 폴링만으로도 확인할 수 있지만, 2,000건을 보내고 10초마다 상태를 조회하면 필요 없는 호출이 쌓입니다. 결과를 받을 시스템이 있다면 POST /webhooks로 수신 주소를 등록하고, 발송이 끝나는 시점에 알림을 받는 편이 효율적입니다.
등록할 때 정하는 값은 세 가지입니다. 수신 주소는 공개 HTTPS 주소여야 하고, 받을 알림은 send.completed·send.failed 같은 발송 결과와 subscriber.created·subscriber.updated·subscriber.unsubscribed·subscriber.resubscribed·subscriber.deleted 같은 구독자 변경 이벤트 중에서 고릅니다. 전달 성공 확인은 HTTP 응답 상태(기본) 또는 저장 확인값 검사 중에서 수신 시스템에 맞게 선택합니다.
전달 성공 확인 두 가지
HTTP 응답 상태 방식은 수신 서버가 2xx를 돌려주면 전달 완료로 봅니다. 저장 확인값 방식은 수신 시스템이 데이터를 저장한 뒤 정해진 확인값을 응답 본문에 담아야 완료로 인정합니다. 확인값은 EZSENDER_RECEIPT_V1:<이벤트 ID>:<요청 본문의 SHA-256> 형식이고, 해시는 가공 전 UTF-8 본문을 기준으로 계산합니다. 응답 코드가 200이어도 확인값이 없거나 해시가 다르면 실패로 기록됩니다. 수신 측에서 중복 수신을 걸러야 하는 구조라면 저장 확인값 방식을 권합니다.
비밀키와 전달 기록
등록 응답에는 알림 검증용 비밀키(whsec_…)가 한 번만 표시됩니다. 수신 서버가 요청이 이지센더에서 온 것인지 확인하는 값이므로 발급 시점에 보관해야 하고, 다시 조회할 수 없습니다. 전달 결과는 GET /webhooks/{id}/deliveries에서 최근 기록으로 확인합니다. 상태, 시도 횟수, 시각이 남고, 대기 중인 항목은 다음 시도 시각을 볼 수 있습니다. 점검 중에는 알림을 중지했다가 다시 시작할 수 있고, 중지 기간에 발생한 이벤트가 나중에 몰려서 오는지는 수신 로직에서 중복을 견디도록 만들어 두는 편이 안전합니다.

결과 알림 설정 화면. 받을 알림과 전달 성공 확인 방식을 정하고, 등록한 주소의 전달 결과를 최근 20건까지 확인합니다.
단건 알림 API는 지금 어떻게 다뤄야 하나
상담 접수 한 건처럼 수신자가 한 명인 알림은 POST /messages로 보냅니다. 본문에 받는 사람, 보내는 사람, 완성된 제목과 HTML을 담아 한 번에 전달하고, 캠페인 생성이나 주소록 등록이 필요 없습니다. 프로 이상과 messages:send 권한이 필요하고, 이 권한은 기존 키에 자동으로 추가되지 않으므로 키를 새로 만들거나 권한을 확인해야 합니다.
다만 이 기능은 운영 발송이 아직 활성화되지 않은 상태에서 503 Errors.Messages.Unavailable을 돌려줄 수 있습니다. 실제로 지금 운영 환경에서 단건 알림을 호출하면 이 응답이 오는 경우가 있으므로, 접수 알림을 API로 설계할 때는 당장은 발송 작업(send-jobs) 중심으로 구성하고 단건 알림은 테스트 키로 응답 형식만 확인해 두는 편이 현실적입니다. 테스트 환경의 202와 accepted는 모의 결과이고 실제 발송의 증거가 아닙니다. 또 accepted는 SMTP 서버가 접수했다는 뜻이지 받은편지함 도착이나 열람을 보장하지 않습니다.
웹에서 직접 보낼까, API로 옮길까
상황 | 웹 직접 발송 | API 연동 |
|---|---|---|
월 1~2회 뉴스레터 | 편함. 작성·검토·예약이 한 화면 | 효과 적음 |
주문·신청 등 업무 이벤트 알림 | 사람이 계속 개입해야 함 | 적합. 누락이 줄어듦 |
여러 시스템의 명단을 합쳐 발송 | 매번 파일을 만들어 올려야 함 | 적합. 구독자·그룹 API로 동기화 |
발송 직전 사람이 내용을 확인해야 함 | 그대로 두는 편이 안전 | 초안 생성까지만 자동화 |
발송 결과를 사내 시스템에 남겨야 함 | 리포트를 보고 옮겨 적음 | 적합. 웹훅으로 자동 기록 |
기준은 “사람이 매번 판단해야 하는가”입니다. 내용 검토가 필요하면 API로 초안과 예약까지만 만들고 마지막 발송은 화면에서 하는 반자동 구성이 안전합니다. 반대로 대상과 문구가 규칙으로 정해지는 알림은 사람이 개입할 여지를 남기지 않는 편이 오히려 사고를 줄입니다.
키 보안과 운영 체크리스트
운영 키는 서버 환경 변수에만 두고, 프런트엔드 번들·앱 배포본·문서에 넣지 않았는지 확인합니다.
키 이름에 용도와 담당 시스템을 적어 두면, 나중에 어느 연동을 끊어야 하는지 헷갈리지 않습니다.
담당자가 바뀌거나 저장소가 공개되는 사고가 있으면 해당 키를 즉시 해제하고 새 키로 교체합니다. 해제된 키로 보낸 요청은 인증되지 않습니다.
호출 기록은 최근 30일 범위에서 확인할 수 있으므로, 장애를 추적할 때는
X-Request-Id와 요청 확인 번호를 함께 남깁니다.운영 전환 전에는 같은 요청을 테스트 키로 한 번, 운영 키로 한 번 실행해 응답 코드와 대상 인원을 비교합니다.
429가 반복되면 호출을 늘리지 말고 발송 건수를 묶거나 예약을 분산합니다.
자주 묻는 질문
202를 받았는데 메일이 오지 않았습니다.
202는 접수 성공입니다. GET /send-jobs/{id}로 상태가 completed인지, failureCount가 늘었는지 확인하세요. 실패가 있다면 캠페인 리포트의 실패 사유에서 주소 오류인지 수신 정책인지 구분할 수 있습니다. 반송된 주소를 그대로 두고 다시 보내면 같은 실패가 반복됩니다.
예약을 취소했는데 발송된 것으로 보입니다.
취소는 처리가 시작되기 전인 예약에만 적용됩니다. 취소 응답의 status가 cancelled인지 확인하고, 이미 sending으로 넘어간 작업은 취소되지 않습니다. 이 경우 발송 결과를 확인한 뒤 필요한 후속 안내를 별도로 설계해야 합니다.
테스트 키로는 되는데 운영 키에서 403이 옵니다.
권한이나 요금제 범위가 원인인 경우가 많습니다. 키에 해당 기능 권한이 있는지, 계정 요금제가 그 기능을 운영에서 제공하는지 확인하세요. 테스트 키는 모든 요금제에서 모의 실행이 되므로, 테스트 성공이 운영 가능을 뜻하지는 않습니다.
웹훅이 두 번 옵니다.
전달이 실패로 기록되면 재시도되므로, 수신 시스템이 같은 이벤트를 두 번 받을 수 있습니다. 이벤트 ID를 기준으로 중복을 걸러내고, 처리 자체를 멱등하게 만드는 것이 정석입니다.
정리
연동의 핵심은 세 가지입니다. 테스트 키로 응답 형식을 먼저 익히고, 발송은 캠페인과 발송 작업을 분리해 접수한 뒤 상태로 확인하고, 결과는 웹훅으로 받아 사내 시스템에 남깁니다. 키 관리와 권한 확인은 기능 구현보다 먼저 끝내 두어야 합니다.
키 발급과 보안 관리는 외부 연동용 API 키 생성·보관·폐기하기, 테스트 실행은 API 테스트 요청과 호출 기록 확인하기, 결과 알림은 API 결과 알림과 전달 결과 확인하기에서 화면과 함께 볼 수 있습니다. 연동 범위가 요금제에 따라 달라지므로 요금제별 API 제공 범위도 함께 확인하세요. 발송 후 성과를 읽는 방법은 열람·클릭 통계 읽는 순서에 정리해 두었습니다.
