콘텐츠로 이동
spacepost문서

오디언스와 연락처

오디언스는 브로드캐스트를 보낼 수 있는 연락처의 목록입니다. 연락처는 정확히 하나의 오디언스에 속합니다. 같은 이메일 주소가 두 오디언스에 있으면 연락처 두 개이며, 각각 자기 수신 거부 상태를 가집니다.

오디언스

섹션 제목: “오디언스”
터미널 창
curl -X POST https://api.spacepost.dev/audiences \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Newsletter" }'
Response
{ "object": "audience", "id": "0192e1c4-0000-7000-8000-0000000000a1", "name": "Newsletter" }

GET /audiences, GET /audiences/{id}, DELETE /audiences/{id}로 구성이 완성됩니다. 오디언스를 삭제하면 그 연락처도 삭제됩니다. 오디언스 이름은 1자 이상 100자 이하입니다.

연락처

섹션 제목: “연락처”

연락처는 오디언스 아래에 있습니다: /audiences/{audienceId}/contacts.

연락처 만들기
emailstring필수

오디언스 안에서 고유합니다. 소문자로 저장됩니다. 중복 생성은 422를 반환합니다.

first_namestring선택

최대 100자. {{{FIRST_NAME}}}에 사용됩니다.

last_namestring선택

최대 100자. {{{LAST_NAME}}}에 사용됩니다.

unsubscribedboolean선택

이미 수신 거부 상태로 연락처를 만듭니다(예: 발송 제외 목록을 가져올 때). 기본값은 false입니다.

contacts.ts
import { SpacePost } from "@spacepost/node";


const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);


const { data: audience, error } = await spacepost.audiences.create({ name: "Newsletter" });
if (error) throw new Error(error.message);


// Create
await spacepost.contacts.create({
  audienceId: audience.id,
  email: "ada@example.com",
  firstName: "Ada",
  lastName: "Lovelace",
});


// Read by email (or by id)
const { data: contact } = await spacepost.contacts.get({ audienceId: audience.id, email: "ada@example.com" });
console.log(contact?.unsubscribed);


// Update
await spacepost.contacts.update({ audienceId: audience.id, email: "ada@example.com", firstName: "Augusta" });


// List, newest first
const { data: page } = await spacepost.contacts.list({ audienceId: audience.id, limit: 50 });
console.log(page?.data.length, page?.has_more);


// Unsubscribe manually, then delete
await spacepost.contacts.update({ audienceId: audience.id, email: "ada@example.com", unsubscribed: true });
await spacepost.contacts.remove({ audienceId: audience.id, email: "ada@example.com" });
터미널 창
AUD=0192e1c4-0000-7000-8000-0000000000a1


# create
curl -X POST https://api.spacepost.dev/audiences/$AUD/contacts \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com", "first_name": "Ada", "last_name": "Lovelace" }'
# => { "object": "contact", "id": "..." }


# get by email (URL-encode the @) or by id
curl "https://api.spacepost.dev/audiences/$AUD/contacts/ada%40example.com" -H "Authorization: Bearer $SPACEPOST_API_KEY"


# update
curl -X PATCH "https://api.spacepost.dev/audiences/$AUD/contacts/ada%40example.com" \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "unsubscribed": true }'


# delete
curl -X DELETE "https://api.spacepost.dev/audiences/$AUD/contacts/ada%40example.com" -H "Authorization: Bearer $SPACEPOST_API_KEY"

연락처는 다음과 같은 모양입니다.

{
  "object": "contact",
  "id": "0192e1c4-0000-7000-8000-0000000000c1",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "created_at": "2026-10-23T14:00:00.000Z",
  "unsubscribed": false
}

DELETE는 { "object": "contact", "contact": "ada@example.com", "deleted": true }를 반환합니다. idOrEmail이 필요한 곳에는 연락처 ID나 이메일 주소 중 아무거나 전달할 수 있습니다.

수신 거부

섹션 제목: “수신 거부”

unsubscribed: true인 연락처는 모든 브로드캐스트에서 건너뜁니다. 연락처는 이메일의 링크를 통해 직접 수신 거부하며(수신 거부), 다른 경로로 옵트아웃을 알게 되었을 때는 API로 플래그를 설정할 수 있습니다.

가져오기

섹션 제목: “가져오기”

요청 한도(Free와 Pro는 초당 10건)를 지키며 반복문으로 가져오세요.

for (const row of rows) {
  const { error } = await spacepost.contacts.create({ audienceId, email: row.email, firstName: row.first });
  if (error?.name === "rate_limit_exceeded") await new Promise((r) => setTimeout(r, 1000));
}

수신에 동의한 사람만 가져오세요. 규정 준수를 참고하세요.