オーディエンスとコンタクト

オーディエンスは、一斉配信の送信先となるコンタクトのリストです。コンタクトは必ず 1 つのオーディエンスに属します。同じメールアドレスが 2 つのオーディエンスにある場合は 2 つのコンタクトとなり、それぞれ独自の配信停止の状態を持ちます。

オーディエンス

cURL
Node.js

curl -X POST https://api.spacepost.dev/audiences \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Newsletter" }'

{ "object": "audience", "id": "0192e1c4-0000-7000-8000-0000000000a1", "name": "Newsletter" }

const { data } = await spacepost.audiences.create({ 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 です。

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" });

cURL
Python

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"

base = f"https://api.spacepost.dev/audiences/{audience_id}/contacts"
h = {"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"}

requests.post(base, headers=h, json={"email": "ada@example.com", "first_name": "Ada"})
requests.patch(f"{base}/ada@example.com", headers=h, json={"unsubscribed": True})

コンタクトは次のような形式です。

{
  "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 は 1 秒に 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));
}

インポートするのは、あなたからのメールを受け取ることに同意した人だけにしてください。コンプライアンスをご覧ください。