개발자 API
메일리 API를 이용하면 외부 시스템에서 구독자를 조회·등록·수정하고, 그룹을 관리하며, 자동 이메일을 실행하고, 뉴스레터 데이터를 가져올 수 있습니다. 서버 간(server-to-server) 요청만 지원하며, 일반 HTML 폼에서의 직접 요청은 허용되지 않습니다.
기본 정보
| 항목 | 값 |
|---|---|
| Base URL | https://api.maily.so |
| 인증 | 모든 요청 헤더에 Authorization: Bearer {API_KEY} |
| 데이터 형식 | 요청·응답 모두 JSON (경로 끝에 .json 사용) |
| 요청 제한 | IP당 초당 20회 (초과 시 429 Rate Limit Exceeded) |
아래 경로의 {스페이스 주소}는 뉴스레터 주소(space_url)입니다. 숫자 ID가 아니라 https://maily.so/@내주소의 주소 부분을 그대로 사용합니다.
API 키 발급
- 좌측 메뉴 개발자 도구 → 개발자 API로 이동합니다.
- API 키(토큰)를 생성합니다. 이미 있으면 그대로 사용하고, 노출되었을 때는 재발급으로 새 토큰을 만들 수 있습니다.
- 발급한 토큰을 요청 헤더
Authorization: Bearer {API_KEY}에 넣어 호출합니다.
토큰은 뉴스레터 소유자 계정에 종속됩니다. 재발급하면 이전 토큰은 즉시 무효화되므로, 연동 중인 시스템의 토큰도 함께 교체해야 합니다. 이 토큰은 AI 에이전트 연동(MCP)에서도 같은 값을 사용하므로, 재발급하면 연결해 둔 AI 에이전트도 함께 끊깁니다.
플랜별 사용 범위
개발자 API는 브랜딩 플랜 이상에서 사용할 수 있으며, 활성 비즈니스 계정이 필요합니다. 기능에 따라 요구 플랜이 다릅니다.
- 조회 API (구독자 목록·집계, 이메일 목록) — 브랜딩 플랜 이상
- 관리 API (구독자 등록·수정·취소, 그룹 추가·제외, 자동 이메일 실행) — 마케팅 플랜
AI 에이전트(Claude·Cursor 등)로 같은 데이터를 다루려면 서버를 만들 필요 없이 MCP 연동을 쓰면 됩니다. 토큰은 위에서 발급한 것과 같은 값을 쓰며, 마케팅 플랜에서 제공됩니다. 자세한 내용은 AI 에이전트 연동 (MCP) 도움말을 참고하세요.
조회 API
구독 데이터를 읽는 API입니다. (브랜딩 플랜 이상)
구독자 목록 조회
GET /api/{스페이스 주소}/subscriptions.json
구독자 목록을 최신순으로 조회합니다. 한 페이지에 100명씩 반환됩니다.
| 파라미터 | 필수 | 설명 |
|---|---|---|
| page | 선택 | 페이지 번호 (기본 1) |
응답: 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개씩 반환됩니다.
| 파라미터 | 필수 | 설명 |
|---|---|---|
| page | 선택 | 페이지 번호 (기본 1) |
| status | 선택 | 상태로 필터 (예: published) |
| order_by | 선택 | published_at 지정 시 발행일순, 그 외에는 생성일순(기본) |
| posting_type | 선택 | 발행 유형으로 필터 |
응답: notes 배열과 함께 current_page, is_last_page를 반환합니다.
관리 API
구독자·그룹·자동 이메일을 제어하는 API입니다. (마케팅 플랜)
구독자 신규 등록
POST /api/{스페이스 주소}/subscriptions.json
새 구독자를 등록합니다. 기본적으로 웰컴 레터가 발송됩니다.
| 파라미터 | 필수 | 설명 |
|---|---|---|
| 필수 | 구독자 이메일 | |
| name | 선택 | 구독자 닉네임 |
| welcome_letter | 선택 | 웰컴 레터 발송 여부 (기본 true, 불리언 false로 보내면 미발송) |
| marketing_agreement | 선택 | 마케팅 정보 수신 동의 여부 |
| marketing_agreed_at | 선택 | 마케팅 동의 시각 |
구독자 정보 수정
PUT /api/{스페이스 주소}/subscriptions/update_if_exist.json
이메일로 기존 구독자를 찾아 정보를 수정합니다. 해당 이메일 구독자가 없으면 오류를 반환합니다.
| 파라미터 | 필수 | 설명 |
|---|---|---|
| 필수 | 수정할 구독자 이메일 (대상 식별용) | |
| name | 선택 | 닉네임 변경 |
| marketing_agreement | 선택 | 마케팅 정보 수신 동의 여부 |
| marketing_agreed_at | 선택 | 마케팅 동의 시각 |
구독자 삭제 (구독 취소)
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
특정 구독자에게 자동 이메일 트리거를 실행합니다.
| 파라미터 | 필수 | 설명 |
|---|---|---|
| automated_email_trigger_ext_id | 필수 | 실행할 자동 이메일 트리거 ID |
| 필수 | 이메일을 받을 구독자 |
응답·에러 처리와 테스트
각 API의 상세 응답 형식과 에러 처리, 실제 호출 테스트는 로그인 후 개발자 도구 → 개발자 API 메뉴의 실행해보기에서 확인할 수 있습니다. 이벤트 발생 시 실시간 알림을 받고 싶다면 웹훅을 함께 활용하세요.
