跳转到内容
spacepost文档

受众与联系人

受众是一份联系人名单，你可以向其发送群发。一个联系人只属于一个受众；同一个邮箱地址出现在两个受众中，就是两个联系人，各自拥有独立的退订状态。

受众

Section titled “受众”
终端窗口
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 个字符。

联系人

Section titled “联系人”

联系人位于其所属受众之下：/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，也可以传邮箱地址。

退订

Section titled “退订”

unsubscribed: true 的联系人会被所有群发跳过。联系人可以通过邮件中的链接自行退订（退订）；当你在其他渠道得知某人退出时，也可以通过 API 设置该标记。

导入

Section titled “导入”

使用循环导入，并遵守速率限制（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));
}

只导入同意接收你邮件的人。参见合规。