이지센더 개발자 센터

대량메일 발송 API,
연결부터 결과 확인까지

이지센더 뉴스레터 플랫폼을 기존 서비스와 연결하세요. API 설정에서 키를 만들고 주소록 관리, 캠페인 조회와 대량메일 발송 요청을 실행한 뒤 결과까지 확인할 수 있습니다.

로그인하면 내 계정의 실행 화면으로 연결됩니다. 문서는 로그인 없이 볼 수 있습니다.

  • 필요한 권한으로 키를 만들고 연결 확인
  • 키에 맞춰 테스트·운영 환경 자동 선택
  • 응답·호출 기록·발송 상태를 같은 곳에서 확인

화면으로 먼저 살펴보세요

사용 흐름 예시
계정 설정 API 연동테스트

새 API 키가 준비되었습니다

키 이름

주소록 연동

주소록 그룹 조회주소록 그룹 편집
새로 만든 키로 바로 확인

키를 고르면 환경도 함께 선택됩니다.

API 설정에서 키를 만들고 ‘이 키로 바로 확인’을 누르세요. 기존 키는 보관한 비밀키만 입력하면 됩니다.

예시 화면입니다. 실제 호출은 내 계정의 API 설정에서 실행합니다.

테스트 키로 먼저 확인

모의 데이터로 요청과 응답을 확인합니다. 실제 주소록 변경이나 메일 발송, 외부 웹훅 전송은 없습니다.

운영 키로 실제 연결

실제 계정의 데이터를 조회·변경하고 메일을 발송합니다. 필요한 권한과 요청 대상을 확인한 뒤 실행하세요.

필요한 연동 범위에 맞춰 선택하세요

테스트 환경에서 먼저 확인하고 운영 환경으로 연결하세요. 운영 요청에는 현재 계정의 요금제와 업무 권한, API 키 권한이 함께 적용됩니다.

모든 요금제
모의 테스트·연결 확인·기존 발송 작업의 결과 조회와 취소
스탠다드 이상
수신자·필드(정보항목)·세그먼트 연동, 기본 자동화, 수신자 결과 알림
프로 이상
단건 알림 발송, 캠페인·그룹·템플릿·첨부파일·성과·뉴스레터 연동과 발송 결과 알림
엔터프라이즈
프로 제공 기능과 주소록·발신 주소 관리

기본 자동 메일은 스탠다드부터, 조건·분기·다단계 자동화는 프로부터 제공합니다. 작업 접수 후의 결과 조회와 취소는 기존 작업의 소유권과 키 권한이 유지되는 동안 이용할 수 있습니다.

연동 가이드

서버 연동에 필요한 기본 정보

API 설정에서 동작을 확인한 뒤 아래 요청 형식과 코드 예제를 서비스에 적용하세요.

API 기본 주소 (Base URL)

외부 프로그램이 이지센더 기능을 이용할 때 쓰는 주소의 공통 부분입니다. 이 주소 뒤에 기능별 경로를 붙여 요청합니다.

https://ezsender.net/api/v1

예: 인증 확인 요청 주소

https://ezsender.net/api/v1/auth-check

기본 주소만 브라우저에서 열면 404가 표시됩니다. 별도 웹페이지가 없는 것이므로 정상입니다. 실제 API 요청에는 인증 정보를 함께 보내야 합니다.

인증

X-EZSENDER-ID: YOUR_API_ID

X-EZSENDER-SECRET: YOUR_SECRET_KEY

계정 설정 → API 설정에서 발급합니다. 인증 정보는 고객 브라우저 코드에 포함하지 말고 서비스 서버에서 사용하세요.

요청 형식

모든 요청 본문은 JSON이며, 응답도 JSON으로 반환됩니다. 인증 정보는 계정 설정의 API 설정 화면에서 생성합니다.

{
  "code": "Errors.Data.InvalidRequest",
  "httpStatusCode": 400,
  "message": "잘못된 요청입니다."
}

응답의 X-Request-Id로 API 설정의 호출 기록을 찾을 수 있습니다. 잘못된 JSON·ID·시간은 실행하지 않고 400으로 반환합니다. 401은 인증, 403은 권한·한도, 404는 소유 리소스 없음, 409는 현재 상태나 요청 키 충돌입니다. 429는 Retry-After 이후 재시도하세요.

인증 확인 예시

curl -X GET "https://ezsender.net/api/v1/auth-check" \
  -H "X-EZSENDER-ID: YOUR_API_ID" \
  -H "X-EZSENDER-SECRET: YOUR_SECRET_KEY" \
  -H "X-EZSENDER-Environment: test"

단건 알림 운영 접수 상태

운영 단건 알림 발송 연결이 준비되지 않아 신규 접수를 사용할 수 없습니다. 테스트 키의 모의 실행과 기존 접수 조회는 가능합니다.

캠페인 발송과 단건 알림은 준비 상태가 다를 수 있습니다. 503 Errors.Messages.Unavailable이면 발신 주소를 바꿔 반복하지 말고 연결 상태를 확인하세요.

수신자 필드(정보항목)부터 준비하세요

기본 이름·이메일은 name·email로 바로 입력합니다. phone(연락처), memo(메모), 회사명·직함 및 customFields는 주소록의 ‘필드(정보항목)’에서 먼저 등록해야 합니다. 문서에 필드가 있어도 이 계정에 등록되지 않은 값은 테스트·운영 모두 400으로 거절합니다.

API로 준비하려면 GET /address-books/custom-fields로 조회하고 POST /address-books/custom-fields에 {"name":"연락처","code":"{{phone}}","type":"text"} 또는 {"name":"메모","code":"{{memo}}","type":"text"}를 전송하세요. custom_fields:write 권한이 필요하며 테스트 키의 항목은 해당 키에만 등록됩니다.

POST /subscribers는 subscribers 배열로 등록합니다. PATCH는 { "emails": ["reader@example.test"], "status": "unsubscribed" }, DELETE는 { "emails": ["reader@example.test"] }로 요청합니다. 두 메서드는 subscribers 배열을 등록 요청으로 처리하지 않습니다.

첫 연동부터 결과 확인까지

  1. 01

    API 설정에서 연결 확인

    필요한 권한으로 테스트 키를 만들고 ‘이 키로 바로 확인’을 누릅니다. 비밀키가 유효한지 확인한 뒤 모의 데이터로 기능을 실행해 보세요.

  2. 02

    발송 작업 접수

    운영 전환 후 캠페인을 만들고 발송 작업을 접수합니다. 새 요청마다 Idempotency-Key를 발급하고 재시도에는 같은 값을 유지합니다.

  3. 03

    완료 결과 확인

    sendJob.id로 진행 상태를 조회하거나 결과 알림을 등록합니다. 202 접수는 배달 완료를 의미하지 않습니다.

샘플 데이터로 바로 시작하세요

새 테스트 키에는 그룹·수신자·캠페인 ID 1, 활성 자동화 ID 1과 작성 중 자동화 ID 2가 준비되어 있습니다. 데이터는 키마다 분리되며 최대 수신자 2,000명·저장 공간 5MiB를 사용할 수 있습니다. 실제 메일과 외부 웹훅은 전송되지 않습니다.

같은 요청은 한 번만

발송 작업 접수와 자동화 실행에는 Idempotency-Key가 필요합니다. 응답이 끊기면 같은 요청·같은 키로 재시도해 기존 결과를 받으세요. 같은 키에 다른 내용을 보내면 409입니다. 예약 변경과 취소는 처리가 시작되기 전까지 가능합니다.

시간과 환경을 명확하게

예약 시각은 2026-12-01T09:00:00+09:00처럼 시간대를 포함합니다. X-EZSENDER-Environment를 명시하면 키 환경이 다를 때 요청을 실행하지 않습니다.

첨부파일·개인화·구독 확인 연결하기
첨부파일
첨부파일 업로드로 받은 ID를 캠페인의 attachmentIds에 넣은 뒤 발송 작업을 접수하세요. 파일당 5MiB까지이며 접수한 파일은 발송 시점에도 같은 내용으로 사용합니다. 목록에서 사용 중인 파일은 삭제할 수 없습니다.
발송할 때만 바뀌는 개인화
기존 수신자를 대상으로 자동화 실행에 공통 variables와 수신자별 recipientVariables를 전달하세요. 제목·미리보기 문구·본문의 {{이름}}·{{이메일}} 같은 변수에 적용되고 주소록 원본은 유지됩니다. 수신자별 값이 공통 값보다 우선하며, 수신거부 링크 등 시스템 변수는 변경할 수 없습니다.
구독 확인 후 등록
구독 확인 메일 요청에 그룹과 이메일을 전달하면 수신자가 메일의 확인 버튼에 동의한 뒤 등록됩니다. 202는 확인 메일 접수 상태이며 구독 완료가 아닙니다. 링크를 여는 것만으로는 동의 처리하지 않습니다. 테스트 키는 실제 확인 메일을 보내지 않습니다.

외부 서비스로 결과 받기

공개 HTTPS 주소(443 포트)를 등록하면 발송 결과와 수신자 변경을 아래 7가지 이벤트로 받을 수 있습니다. 생성할 때 제공되는 서명 비밀값은 서버에 저장하세요. 테스트 환경에서는 외부로 전송하지 않습니다.

send.completed
메일 발송 완료
send.failed
메일 발송 실패
subscriber.created
수신자 등록
subscriber.updated
수신자 정보 변경
subscriber.unsubscribed
구독 취소
subscriber.resubscribed
재구독
subscriber.deleted
수신자 삭제
서명 확인
X-EZSENDER-Signature: t=시간,v1=서명
HMAC-SHA256(secret, t + '.' + 가공 전 요청 본문)을 timingSafeEqual 같은 상수 시간 비교 함수로 확인합니다. 수신 시각과 5분 이내인지도 확인하세요.
재시도와 중복 처리
X-EZSENDER-Event-Id로 중복 이벤트를 구분합니다. 10초 내 선택한 확인 방식으로 성공이 확인되지 않으면 30초부터 간격을 늘려 최대 8회 시도합니다. 전달 기록은 30일 보관합니다.

전달 성공 확인 방식

responseVerification을 생략하면 http_status를 사용합니다. HTTP 2xx 응답으로 전달 완료를 확인하며 기존 연동 방식은 유지됩니다. receipt_v1을 선택하면 HTTP 2xx와 저장 확인값을 함께 검사합니다. Google Apps Script처럼 저장 오류에도 HTTP 200을 반환할 수 있는 수신기에 사용하세요.

  1. 수신 시스템에서 요청을 검증하고 이벤트 ID로 중복을 확인한 뒤 저장을 마칩니다. 이미 저장된 동일 이벤트의 재시도에도 같은 확인값을 반환하세요.
  2. 가공 전 UTF-8 요청 본문의 SHA-256을 소문자 16진수로 계산합니다. JSON을 다시 직렬화한 문자열을 사용하면 일치하지 않을 수 있습니다.
  3. HTTP 2xx 응답 본문에 아래 확인값을 반환합니다. 이벤트 ID는 요청 본문의 id와 X-EZSENDER-Event-Id에 있습니다.

EZSENDER_RECEIPT_V1:<eventUUID>:<sha256(raw request body)>

일반 텍스트 및 Google HtmlService의 HTML 안에 있는 확인값을 지원합니다. 응답은 압축하지 않은 64KiB 이내로 반환하고 리다이렉트하지 마세요. 확인값 누락·불일치·응답 읽기 실패는 HTTP 200이어도 재시도 대상입니다. 확인값은 수신 시스템의 저장 완료 응답을 검사하는 기능이며 요청 서명 검증을 대체하지 않습니다. 테스트 환경은 외부 전송 없이 설정과 응답 형식만 모의 처리합니다.

send.completed와 send.failed의 data.sendJob.subject는 접수 당시 저장한 기본 이메일 제목입니다. 일반 발송은 variantSubjects: null, A/B는 variantSubjects: {a, b}로 버전별 제목도 받습니다. A/B의 기본 제목을 승자 제목으로 해석하지 마세요. 과거 이벤트 본문은 유지되므로 제목이 없다면 발송 작업 조회 API를 사용하세요. 저장 당시 제목을 알 수 없으면 null입니다.

결과 이벤트 예시
{
  "id": "2d59cd78-69d6-451b-a359-c061c59bfc43",
  "type": "send.completed",
  "createdAt": "2026-12-01T00:02:00.000Z",
  "data": {
    "sendJob": {
      "id": "a112ac74-6e95-4b56-99a4-6fe16f2a8140",
      "campaignId": 10,
      "subject": "12월 이지센더 소식",
      "variantSubjects": null,
      "status": "completed",
      "scheduledAt": "2026-12-01T00:00:00.000Z",
      "recipientCount": 120,
      "successCount": 120,
      "failureCount": 0,
      "completedAt": "2026-12-01T00:02:00.000Z"
    }
  }
}

직접 실행할 준비가 되셨나요?

API 설정에서 키 선택부터 호출과 결과 확인까지 이어서 진행하세요.

내 계정에서 API 실행하기

API REFERENCE

필요한 기능을 찾아보세요.

130개 기능의 필수 항목, 권한, 예시를 한곳에서 확인합니다.

GET/api/v1/auth-check

인증 확인

발급된 API ID와 secret key 조합이 유효한지 확인합니다.

HTTP 200유효한 API 키

운영: 모든 요금제 · 1,000회/분모의 테스트는 모든 요금제에서 계정당 120회/분입니다. 운영 한도는 같은 계정의 같은 종류 기능에서 함께 사용합니다.

API 설정에서 실행하기

요청 본문이 없습니다.

cURL

curl -X GET "https://ezsender.net/api/v1/auth-check" \
  -H "X-EZSENDER-ID: YOUR_TEST_API_ID" \
  -H "X-EZSENDER-SECRET: YOUR_TEST_SECRET" \
  -H "X-EZSENDER-Environment: test"