Contactos, audiências e difusões

Quatro espaços de nomes cobrem as pessoas a quem escreve. Os contactos são o livro de endereços do espaço de trabalho, as audiências são listas de contactos com nome, uma difusão envia uma mensagem a todas as pessoas de algumas audiências, e a lista de supressão contém os endereços para os quais o espaço de trabalho não envia. Cada comando chama um método do SDK, por isso as páginas do SDK descrevem as mesmas chamadas com mais detalhe.

• —Um contacto não tem id. O seu endereço é a chave que cada comando de contacts aceita, sem espaços e em minúsculas, por isso [email protected] e [email protected] são o mesmo contacto. Uma audiência tem um id aud_, uma difusão um id brd_, e uma supressão o id que suppressions list mostra.
• —Cada contacto está na audiência predefinida enquanto existir. Essa audiência não pode ser eliminada, esvaziada nem reduzida, e nela builtin é default.
• —O livro de endereços pertence ao espaço de trabalho, por isso cada membro e cada chave leem e escrevem o mesmo.
• —Cada espaço de nomes responde também ao seu singular, como em openemail contact get, e os aliases habituais funcionam: ls, show, new, edit e rm. Em suppressions, cujos verbos são add e remove, new leva a add e rm a remove.

O livro de endereços do espaço de trabalho: as pessoas a quem um membro escreveu a partir do editor da aplicação, mais quem tiver sido guardado à mão. O correio que chega não acrescenta ninguém, e um envio pela API ou pela CLI também não.

Listas de contactos com nome, até 100 por espaço de trabalho. Um endereço tem de ser um contacto antes de entrar numa, exceto através de import-contacts, que guarda os endereços novos pelo caminho.

Uma mensagem para todas as pessoas de até 10 audiências, enviada como uma cópia separada para cada pessoa, com os campos de fusão preenchidos e uma ligação para cancelar a subscrição. Cada cópia é um email normal com o seu próprio id msg_, eventos e webhooks.

Os endereços para os quais este espaço de trabalho não envia: devoluções permanentes e queixas, registadas quando acontecem, e qualquer endereço que acrescente à mão. Um envio para um deles é recusado para esse destinatário antes de sair alguma coisa.

A maioria dos comandos precisa do scope de leitura ou de escrita do seu espaço de nomes. Alguns precisam de outro, porque leem ou alteram outra coisa:

• —Uma chave limitada a determinados endereços ou domínios lê e escreve o mesmo livro de endereços que qualquer outra chave. Só vê as difusões enviadas a partir de um endereço ou domínio que tem, recebe apenas os contactos guardados de list-people, e é recusada com 422 capability_unsupported por contacts list-threads, activity, block e unblock, e por suppressions add e remove.
• —Um início de sessão no navegador de um membro que só alcança alguns endereços é recusado com 422 capability_unsupported em cada comando de contacts, audiences e broadcasts. suppressions add recusa um início de sessão no navegador de qualquer pessoa que não seja o proprietário do espaço de trabalho.

Crie uma audiência a partir de um ficheiro e conte depois quem uma difusão para ela alcançaria. import-contacts guarda os endereços que ainda não são contactos, e voltar a executá-lo não cria nem acrescenta nada duas vezes.

[  { "email": "[email protected]", "name": "Ada Lovelace" },  { "email": "[email protected]", "name": "Grace Hopper" },  { "email": "[email protected]" }]

AUDIENCE=$(openemail audiences create --name 'Product updates' --json | jq -r .id)openemail audiences import-contacts "$AUDIENCE" --contacts @contacts.jsonopenemail broadcasts preview --audience-ids "$AUDIENCE"

Verifique uma difusão com --dry-run, que mostra o pedido e não envia nada, e depois envie-a. A difusão é criada de imediato e enviada em segundo plano, por isso consulte get para a acompanhar. Este corpo não inclui {{unsubscribeUrl}}, por isso cada cópia recebe um rodapé de uma linha para cancelar a subscrição.

{  "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>",  "scheduledAt": "2026-10-01T09:00:00Z"}

openemail broadcasts send --data @broadcast.json --dry-runBROADCAST=$(openemail broadcasts send --data @broadcast.json --yes --json | jq -r .id)openemail broadcasts get "$BROADCAST"openemail broadcasts stats "$BROADCAST" --grain day

Veja quem uma difusão não alcançou. --ndjson mostra um destinatário por linha, e --all --json um único documento com todas as páginas.

openemail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --filter bounced --ndjson | jq -r .emailopenemail broadcasts list-recipients brd_5a8c1e3f7b2d94a06c8e1f3b --filter not_opened --all --json | jq ".items | length"openemail suppressions list --reason bounce --all --max 50

Copie os membros com subscrição de uma audiência para outra. jq transforma o fluxo no corpo que add-contacts aceita, e --data - lê-o de stdin. --max 200 limita-o aos 200 endereços que uma chamada aceita.

openemail audiences list-contacts aud_9f2c4b7e1a0d63d84c5f2e7b --statuses subscribed --max 200 --ndjson \  | jq -s '{ emails: map(.email) }' \  | openemail audiences add-contacts aud_1c4e7a9b2d0f36e85a7c1b4d --data -

Elimine cada contacto que o editor registou num domínio. delete-many aceita até 200 endereços por chamada, por isso xargs -n 200 divide uma lista mais longa. Verifique primeiro os lotes com --dry-run, porque não é possível anular.

openemail contacts list --source auto --all --ndjson \  | jq -r 'select(.email | endswith("@old-vendor.example")) | .email' > leaving.txtxargs -n 200 openemail contacts delete-many --dry-run < leaving.txtxargs -n 200 openemail contacts delete-many --yes < leaving.txt

Deixe de enviar para um endereço, volte a permitir outro e bloqueie um remetente. removable diz que linhas suppressions remove aceita.

openemail suppressions add --email [email protected]openemail suppressions list --q [email protected] --json | jq -r '.items[] | select(.removable) | .id'openemail suppressions remove 7b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e --yesopenemail contacts block [email protected]

Estes comandos pedem-lhe confirmação num terminal antes de serem executados:

• —--yes confirma por si. Sem supervisão, com --json ou --no-input, em CI ou sem terminal, um comando que perguntaria para com Refusing to run unattended. Pass --yes to confirm. e o código de saída 2.
• —--dry-run mostra o pedido que o comando enviaria e sai com o código 0, sem perguntar e sem alterar nada.
• —Com um início de sessão no navegador, audiences delete pede primeiro um código de verificação, como faz a aplicação web. --yes nunca o salta, e sem supervisão o comando para com o código de saída 4. Execute antes openemail verify, ou use uma chave de API, à qual nunca é pedido.
• —audiences empty nunca pede um código de verificação, por isso verifique o id antes de passar --yes.

Cada comando que lista lê uma página. Quando restam mais, passe a --cursor o cursor que mostrou, com os mesmos filtros, ou leia-as todas:

• —--all lê todas as páginas e transmite os itens: uma tabela num terminal, e um objeto JSON por linha quando encaminhado ou com --ndjson.
• —--max <n> para depois desse número de itens, e implica --all.
• —--json mostra um único documento { items, hasMore, nextCursor }, também com --all.
• —Um cursor mal formado ou expirado dá 400 invalid_cursor. Comece de novo sem ele.

• —contacts create recusa um endereço que já está no livro com 409 contact_exists, por isso uma nova tentativa nunca substitui um nome que alguém editou. contacts save nunca recusa: guarda, mantém ou recupera o endereço, seja qual for o estado.
• —contacts delete aceita também um endereço que só foi visto no correio, o que retira essa pessoa de list-people. O correio fica. Não é possível anular: guardar de novo o endereço começa um contacto sem nome, sem notas e sem outra audiência além da predefinida.
• —O endereço é a identidade de um contacto, por isso contacts update não o pode alterar. Mover um contacto é um delete e um create.
• —contacts set-photo lê a imagem de um ficheiro, ou de stdin com -. Passe --content-type, como image/jpeg: sem ele a imagem pode ir como application/octet-stream, que o servidor recusa com 422 invalid_image.
• —broadcasts send --scheduled-at aceita uma hora ISO 8601 como 2026-10-01T09:00:00Z, ou uma duração ISO 8601 como PT2H ou P1D, até 365 dias no futuro. Os atrasos curtos que send --at aceita, como 2h, são aqui recusados.
• —Os campos de fusão funcionam em --subject, --html e --text: {{firstName}}, {{lastName}}, {{name}}, {{email}} e {{unsubscribeUrl}}, cada um com um valor alternativo depois de uma barra, como em {{firstName|there}}. Um corpo que não inclui {{unsubscribeUrl}} recebe um rodapé de uma linha para cancelar a subscrição. Um modelo é enviado tal como está, por isso ponha a ligação no modelo.
• —Uma difusão é verificada contra os envios mensais do plano antes de se escrever o que quer que seja, e cada cópia conta como um envio. Uma que a quota não consegue cobrir é recusada com 429 send_quota_exceeded, e nada fica para trás.
• —Passe a sua própria --idempotency-key a broadcasts send quando um script puder executar o passo de novo. A mesma chave responde com a difusão que criou em vez de enviar uma nova.
• —Um contacto que cancela a subscrição de uma difusão continua na audiência com unsubscribedAt definido, e as difusões seguintes para essa audiência ignoram-no. audiences list-contacts --statuses unsubscribed lista-os.
• —Uma devolução permanente fica na lista de supressão. suppressions remove recusa-a com 409 suppression_not_removable, e removable em cada linha indica-o de antemão.