오디언스로 보내기

하나 이상의 오디언스에 있는 모든 사람에게 메시지 하나를, 사람마다 별도의 사본으로, 각 연락처에 맞게 개인화해 보냅니다. 각 사본의 받는 사람은 정확히 한 명이고 cc나 bcc가 없어서 누구도 또 누구에게 갔는지 볼 수 없으며, 각 사본은 자체 msg_ ID, 이벤트, 추적, 웹훅이 있는 일반 이메일입니다. 호출은 곧바로 202로 응답하고 발송은 백그라운드에서 진행되므로 GET /broadcasts/{id}로 따라가세요.

emails:send와 audiences:read가 필요합니다. audienceIds에는 ID가 1~10개 들어갑니다. 본문은 html과/또는 text, 또는 저장된 template에서 오며 둘 다일 수는 없고, 템플릿이 제공하지 않으면 subject가 필수입니다.

curl -X POST "$OE/broadcasts" -H "$AUTH" -H 'content-type: application/json' -d '{  "audienceIds": ["aud_4c1b8e2a7d9f05c36b4e8a71"],  "from": "Acme <[email protected]>",  "subject": "{{firstName|Hello}}, the September release is out",  "html": "<p>Hi {{firstName|there}},</p><p>Here is what changed this month.</p>",  "text": "Hi {{firstName|there}}, here is what changed this month. Unsubscribe: {{unsubscribeUrl}}",  "tags": { "campaign": "release-2026-09" },  "scheduledAt": "PT2H"}'

{  "object": "broadcast",  "id": "brd_5a8c1e3f7b2d94a06c8e1f3b",  "status": "scheduled",  "mode": "live",  "source": "api",  "audienceIds": ["aud_4c1b8e2a7d9f05c36b4e8a71"],  "from": "Acme <[email protected]>",  "subject": "{{firstName|Hello}}, the September release is out",  "counts": {    "recipients": 412,    "created": 0,    "skipped": 0,    "failedToQueue": 0,    "queued": 0,    "sending": 0,    "sent": 0,    "failed": 0,    "cancelled": 0  },  "lastError": null,  "scheduledAt": "2026-09-23T14:00:00.000Z",  "startedAt": null,  "completedAt": null,  "cancelledAt": null,  "createdAt": "2026-09-23T12:00:00.000Z",  "updatedAt": "2026-09-23T12:00:00.000Z",  "replayed": false}

적어도 하나의 오디언스에 있는 모든 연락처이며, 몇 개의 오디언스에 있든 한 번만 셉니다. 두 종류의 연락처는 빠집니다. 선택한 오디언스 중 자신이 속한 모든 곳에서 구독을 해지한 연락처와, 바운스나 신고 때문에 또는 누가 추가해서 주소가 차단 목록에 있는 연락처입니다. 호출 뒤 발송이 닿기 전에 오디언스에 추가된 연락처는 받습니다.

발송은 오디언스를 한 번에 50명씩 훑으며 각 사본을 POST /emails가 쓰는 것과 같은 경로에 넘기므로, 각 사본은 다른 메시지처럼 재시도, 추적, 보고됩니다. POST /broadcasts/preview는 이 호출이 출발할 수를 아무것도 보내지 않고 돌려줍니다.

subject, html, text는 사람마다 채워집니다. 각 필드는 막대 뒤에 대체 값을 받아 연락처에 값이 없을 때 쓰므로, 이름 없이 저장된 연락처에서 {{firstName|there}}는 "there"가 됩니다. html에서는 값이 이스케이프되고, 중괄호 안의 공백은 허용되며, 다른 {{…}}는 쓴 그대로 남습니다.

본문 대신 template을 쓰면 같은 다섯 값이 프롭으로 전달되지만, 템플릿이 선언한 프롭만입니다. firstName을 선언한 템플릿은 그 값을 받고, 선언하지 않은 프롭은 전혀 보내지지 않으므로 알 수 없는 프롭 때문에 사본이 실패하는 일은 없습니다. template.props에 넣은 것은 모든 사본에 똑같이 들어갑니다.

모든 사본에 List-Unsubscribe와 List-Unsubscribe-Post: List-Unsubscribe=One-Click이 붙습니다. 이것 덕분에 메일 클라이언트가 자체 구독 해지 버튼을 보여 줄 수 있고, 대형 메일함 제공자가 대량 메일에 요구하는 것도 이것입니다.

{{unsubscribeUrl}}을 직접 넣지 않은 html이나 text 본문에는 한 줄짜리 바닥글이 붙습니다: "You are receiving this because you are on this mailing list. Unsubscribe". 템플릿은 그대로 보내지므로 템플릿에 {{unsubscribeUrl}}을 넣으세요.

링크는 구독 해지 버튼이 있는 페이지를 열기 때문에, 링크를 가져가는 스캐너는 아무도 구독 해지하지 않지만 메일 클라이언트의 원클릭 요청은 즉시 구독을 해지합니다. 어느 쪽이든 그 사람은 이 브로드캐스트가 간 모든 오디언스에서 구독 해지로 표시되며, 이는 GET /audiences/{id}/contacts의 unsubscribedAt으로 나타납니다. 다른 오디언스, 연락처, 한 통씩 보내는 메일에는 영향이 없습니다.