Listar os destinatários de uma difusão
Todas as pessoas para quem a difusão foi, uma linha por cópia, ordenadas por endereço: o id da cópia, o seu estado, quando foi enviada e entregue, se foi devolvida ou denunciada como spam, quantas vezes foi aberta e clicada, e se a pessoa cancelou a subscrição depois do envio.
Executa a chamada real contra o seu espaço de trabalho, com a sua própria chave.
GET /broadcasts/{id}/recipients
Todas as pessoas para quem a difusão foi, uma linha por cópia, ordenadas por endereço: o id da cópia, o seu estado, quando foi enviada e entregue, se foi devolvida ou denunciada como spam, quantas vezes foi aberta e clicada, e se a pessoa cancelou a subscrição depois do envio.
Parâmetros
idstringobrigatório- No caminho. Um id `brd_` de `POST /broadcasts` ou `GET /broadcasts`.
filterstring- Mantém um grupo: `pending` (ainda em fila ou a enviar), `sent`, `delivered`, `opened`, `not_opened` (enviadas e nunca abertas), `clicked`, `bounced`, `complained`, `failed` (falhadas ou canceladas) ou `unsubscribed`.
qstring- Pesquisa o endereço e o nome, sem distinguir maiúsculas de minúsculas. Até 200 caracteres.
limitinteger- Linhas por página, de 1 a 200. Por omissão, 50.
cursorstring- O `nextCursor` da página anterior, devolvido tal como veio, com os mesmos `filter` e `q`. Guarda onde estava a última linha, por isso uma linha que muda entre páginas nunca interrompe o percurso.
Exemplo
Precisa de emails:read. A resposta é uma página de linhas broadcast_recipient.
curl "$OE/broadcasts/brd_5a8c1e3f7b2d94a06c8e1f3b/recipients?filter=opened&limit=50" -H "$AUTH"{ "object": "list", "data": [ { "object": "broadcast_recipient", "emailId": "msg_01dad25067bc4dac966d515d", "contactId": "6f1c2a8e-3b4d-4e9f-a1c7-2d5e8b0f9a34", "email": "[email protected]", "name": "Ada Lovelace", "status": "sent", "sentAt": "2026-09-23T12:00:09.000Z", "deliveredAt": "2026-09-23T12:00:11.000Z", "bouncedAt": null, "complainedAt": null, "failure": null, "opens": 3, "firstOpenAt": "2026-09-23T12:14:30.000Z", "clicks": 1, "firstClickAt": "2026-09-23T12:15:02.000Z", "unsubscribedAt": null } ], "hasMore": true, "nextCursor": "WyJhZGFAZXhhbXBsZS5jb20iLCJtc2dfMDFkYWQyNTA2N2JjNGRhYzk2NmQ1MTVkIl0"}As aberturas e os cliques excluem proxies de imagens e verificadores de ligações, e ficam em 0 quando a difusão foi enviada com o seguimento desligado.
status é o estado da cópia no registo de envios: queued, scheduled, sending, sent, failed ou cancelled. deliveredAt, bouncedAt e complainedAt são o primeiro email.delivered, email.bounced e email.complained dessa cópia, e failure diz porque é que uma cópia falhou.
unsubscribedAt é quando a pessoa cancelou a subscrição de uma das audiências da difusão depois do envio, pela ligação da difusão ou de outra forma. contactId é null quando o contacto foi eliminado entretanto.
emailId é o id msg_ da cópia. GET /broadcasts/{id}/recipients/{emailId} lê-a com o seu conteúdo, e GET /emails/{id} lê-a como um e-mail enviado.
Recusas
| Estado | Código | Quando |
|---|---|---|
| 400 | invalid_cursor | Na lista de destinatários, um cursor que essa lista não entregou. |
| 403 | insufficient_scope | A chave não tem emails:read. |
| 404 | broadcast_not_found | O id não indica nenhuma difusão deste workspace, ou a chave está limitada a determinados endereços ou domínios e a difusão saiu de um que ela não tem. |
| 404 | recipient_not_found | Em GET /broadcasts/{id}/recipients/{emailId}, um emailId que não é uma cópia desta difusão. |