개발자 API

메일리 API를 이용하면 외부 시스템에서 구독자를 조회·등록·수정하고, 그룹을 관리하며, 자동 이메일을 실행하고, 뉴스레터 데이터를 가져올 수 있습니다. 서버 간(server-to-server) 요청만 지원하며, 일반 HTML 폼에서의 직접 요청은 허용되지 않습니다.

기본 정보

아래 경로의 {스페이스 주소}는 뉴스레터 주소(space_url)입니다. 숫자 ID가 아니라 https://maily.so/@내주소의 주소 부분을 그대로 사용합니다.

API 키 발급

토큰은 뉴스레터 소유자 계정에 종속됩니다. 재발급하면 이전 토큰은 즉시 무효화되므로, 연동 중인 시스템의 토큰도 함께 교체해야 합니다.

▲ 개발자 도구 → 개발자 API 화면

플랜별 사용 범위

개발자 API는 브랜딩 플랜 이상에서 사용할 수 있으며, 활성 비즈니스 계정이 필요합니다. 기능에 따라 요구 플랜이 다릅니다.

조회 API

구독 데이터를 읽는 API입니다. (브랜딩 플랜 이상)

구독자 목록 조회

GET /api/{스페이스 주소}/subscriptions.json

구독자 목록을 최신순으로 조회합니다. 한 페이지에 100명씩 반환됩니다.

응답: subscriptions 배열과 함께 current_page, total_pages, is_last_page를 반환합니다. 각 구독자에는 부가 정보(커스텀 필드)와 멤버십 정보(멤버십 운영 시)가 포함됩니다.

구독자 집계 조회

GET /api/{스페이스 주소}/subscriptions/stats.json

구독자 수를 상태·플랜별로 집계해 반환합니다. 별도 파라미터는 없습니다.

응답: 전체 구독자 수(total_count), 상태별 수(plan_counts — free/canceled 등), 멤버십을 운영 중이면 유료 플랜별 수와 유료 멤버십 수(paid_membership_count)를 포함합니다.

이메일(뉴스레터) 목록 조회

GET /api/{스페이스 주소}/notes.json

발행한 뉴스레터(이메일) 목록을 조회합니다. 한 페이지에 100개씩 반환됩니다.

응답: notes 배열과 함께 current_page, is_last_page를 반환합니다.

관리 API

구독자·그룹·자동 이메일을 제어하는 API입니다. (마케팅 플랜)

구독자 신규 등록

POST /api/{스페이스 주소}/subscriptions.json

새 구독자를 등록합니다. 기본적으로 웰컴 레터가 발송됩니다.

구독자 정보 수정

PUT /api/{스페이스 주소}/subscriptions/update_if_exist.json

이메일로 기존 구독자를 찾아 정보를 수정합니다. 해당 이메일 구독자가 없으면 오류를 반환합니다.

구독자 삭제 (구독 취소)

POST /api/{스페이스 주소}/subscriptions/cancel.json

해당 구독자의 구독을 취소합니다. 환불 가능한 유료 구독이면 환불도 함께 처리됩니다.

그룹에 구독자 추가

POST /api/{스페이스 주소}/subscription_groups/{그룹 ext_id}/add_subscriber.json

특정 구독 그룹에 구독자를 추가합니다.

그룹에서 구독자 제외

POST /api/{스페이스 주소}/subscription_groups/{그룹 ext_id}/remove_subscriber.json

특정 구독 그룹에서 구독자를 제외합니다.

자동 이메일 실행

POST /api/{스페이스 주소}/automated_emails/{자동 이메일 ext_id}/trigger.json

특정 구독자에게 자동 이메일 트리거를 실행합니다.

응답·에러 처리와 테스트

각 API의 상세 응답 형식과 에러 처리, 실제 호출 테스트는 로그인 후 개발자 도구 → 개발자 API 메뉴의 실행해보기에서 확인할 수 있습니다. 이벤트 발생 시 실시간 알림을 받고 싶다면 웹훅을 함께 활용하세요.