Kontakte, Zielgruppen und Broadcasts

Vier Namespaces decken die Menschen ab, denen Sie schreiben. Kontakte sind das Adressbuch des Workspace, Zielgruppen sind benannte Listen von Kontakten, ein Broadcast sendet eine Nachricht an alle in einigen Zielgruppen, und die Sperrliste enthält die Adressen, an die der Workspace nicht sendet. Jeder Befehl ruft eine SDK-Methode auf, die SDK-Seiten beschreiben dieselben Aufrufe also ausführlicher.

• —Ein Kontakt hat keine ID. Seine Adresse ist der Schlüssel, den jeder contacts-Befehl nimmt, ohne umgebende Leerzeichen und in Kleinbuchstaben, [email protected] und [email protected] sind also ein Kontakt. Eine Zielgruppe hat eine aud_-ID, ein Broadcast eine brd_-ID und ein Sperreintrag die ID, die suppressions list ausgibt.
• —Jeder Kontakt ist in der Standard-Zielgruppe, solange es ihn gibt. Diese Zielgruppe lässt sich nicht löschen, leeren oder verkleinern, und builtin ist bei ihr default.
• —Das Adressbuch gehört dem Workspace, daher lesen und schreiben jedes Mitglied und jeder Schlüssel dasselbe.
• —Jeder Namespace hört auch auf seinen Singular, wie in openemail contact get, und die üblichen Aliasse funktionieren: ls, show, new, edit und rm. In suppressions, dessen Verben add und remove heißen, führt new zu add und rm zu remove.

Das Adressbuch des Workspace: die Menschen, denen ein Mitglied aus dem Composer der App geschrieben hat, und alle, die von Hand gespeichert wurden. Eingehende Mail fügt niemanden hinzu, ebenso wenig ein Versand über die API oder die CLI.

Benannte Listen von Kontakten, bis zu 100 in einem Workspace. Eine Adresse muss ein Kontakt sein, bevor sie einer beitritt, außer über import-contacts, das neue Adressen dabei speichert.

Eine Nachricht an alle in bis zu 10 Zielgruppen, als eigene Kopie für jede Person gesendet, mit ausgefüllten Seriendruckfeldern und einem Abmeldelink. Jede Kopie ist eine gewöhnliche E-Mail mit eigener msg_-ID, eigenen Ereignissen und Webhooks.

Die Adressen, an die dieser Workspace nicht sendet: Hard Bounces und Beschwerden, erfasst, sobald sie auftreten, und jede Adresse, die Sie von Hand hinzufügen. Ein Versand an eine davon wird für diesen Empfänger abgelehnt, bevor etwas hinausgeht.

Die meisten Befehle brauchen den Lese- oder Schreib-Scope ihres Namespace. Einige brauchen einen anderen, weil sie etwas anderes lesen oder ändern:

• —Ein Schlüssel, der auf bestimmte Adressen oder Domains beschränkt ist, liest und schreibt dasselbe Adressbuch wie jeder andere Schlüssel. Er sieht nur die Broadcasts, die von einer Adresse oder Domain gesendet wurden, die er umfasst, bekommt von list-people nur die gespeicherten Kontakte und wird mit 422 capability_unsupported abgelehnt von contacts list-threads, activity, block und unblock sowie von suppressions add und remove.
• —Eine Browser-Anmeldung eines Mitglieds, das nur einige Adressen erreicht, wird bei jedem contacts-, audiences- und broadcasts-Befehl mit 422 capability_unsupported abgelehnt. suppressions add lehnt eine Browser-Anmeldung von allen außer dem Eigentümer des Workspace ab.

Eine Zielgruppe aus einer Datei aufbauen und dann zählen, wen ein Broadcast an sie erreichen würde. import-contacts speichert die Adressen, die noch keine Kontakte sind, und ein erneuter Lauf legt nichts doppelt an und fügt nichts doppelt hinzu.

[  { "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"

Einen Broadcast mit --dry-run prüfen, das die Anfrage ausgibt und nichts sendet, und ihn dann senden. Der Broadcast wird sofort angelegt und im Hintergrund gesendet, fragen Sie also get ab, um ihn zu verfolgen. Dieser Body setzt {{unsubscribeUrl}} nicht ein, daher bekommt jede Kopie eine einzeilige Abmeldezeile am Ende.

{  "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

Sehen, wen ein Broadcast nicht erreicht hat. --ndjson gibt einen Empfänger pro Zeile aus, und --all --json ein Dokument mit jeder Seite.

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

Die angemeldeten Mitglieder einer Zielgruppe in eine andere kopieren. jq macht aus dem Stream den Body, den add-contacts nimmt, und --data - liest ihn von stdin. --max 200 begrenzt ihn auf die 200 Adressen, die ein Aufruf annimmt.

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

Jeden Kontakt löschen, den der Composer bei einer Domain erfasst hat. delete-many nimmt bis zu 200 Adressen pro Aufruf, daher teilt xargs -n 200 eine längere Liste auf. Prüfen Sie die Stapel zuerst mit --dry-run, denn es gibt kein Rückgängig.

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

Das Senden an eine Adresse stoppen, eine wieder zulassen und einen Absender blockieren. removable sagt, welche Zeilen suppressions remove annimmt.

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]

Diese Befehle bitten in einem Terminal um Bestätigung, bevor sie laufen:

• —--yes bestätigt für Sie. Unbeaufsichtigt, mit --json oder --no-input, in CI oder ohne Terminal, bricht ein Befehl, der fragen würde, mit Refusing to run unattended. Pass --yes to confirm. und Exit-Code 2 ab.
• —--dry-run gibt die Anfrage aus, die der Befehl senden würde, und endet mit Exit-Code 0, ohne zu fragen und ohne etwas zu ändern.
• —Mit einer Browser-Anmeldung fragt audiences delete zuerst nach einem Bestätigungscode, wie die Web-App. --yes überspringt ihn nie, und unbeaufsichtigt bricht der Befehl mit Exit-Code 4 ab. Führen Sie vorher openemail verify aus oder nutzen Sie einen API-Schlüssel, der nie gefragt wird.
• —audiences empty fragt nie nach einem Bestätigungscode, prüfen Sie also die ID, bevor Sie --yes übergeben.

Jeder Befehl, der auflistet, liest eine Seite. Bleiben weitere, übergeben Sie den ausgegebenen Cursor an --cursor, mit denselben Filtern, oder lesen Sie alle:

• —--all liest jede Seite und streamt die Einträge: eine Tabelle in einem Terminal und ein JSON-Objekt pro Zeile, wenn weitergeleitet oder mit --ndjson.
• —--max <n> hört nach so vielen Einträgen auf und schließt --all ein.
• —--json gibt ein einziges { items, hasMore, nextCursor }-Dokument aus, auch mit --all.
• —Ein fehlerhafter oder veralteter Cursor ist ein 400 invalid_cursor. Beginnen Sie ohne ihn von vorn.

• —contacts create lehnt eine Adresse, die schon im Adressbuch steht, mit 409 contact_exists ab, sodass eine Wiederholung nie einen Namen überschreibt, den jemand bearbeitet hat. contacts save lehnt nie ab: Es speichert, behält oder holt die Adresse zurück, egal in welchem Zustand sie ist.
• —contacts delete nimmt auch eine Adresse, die nur in Mail vorkam, und nimmt diese Person damit aus list-people. Die Mail bleibt. Es gibt kein Rückgängig: Wird die Adresse erneut gespeichert, entsteht ein Kontakt ohne Namen, ohne Notizen und ohne Zielgruppe außer der Standard-Zielgruppe.
• —Die Adresse ist die Identität eines Kontakts, daher kann contacts update sie nicht ändern. Einen Kontakt zu verschieben ist ein delete und ein create.
• —contacts set-photo liest das Bild aus einer Datei oder über stdin mit -. Übergeben Sie --content-type, etwa image/jpeg: Ohne kann das Bild als application/octet-stream gehen, was der Server mit 422 invalid_image ablehnt.
• —broadcasts send --scheduled-at nimmt eine ISO-8601-Zeit wie 2026-10-01T09:00:00Z oder eine ISO-8601-Dauer wie PT2H oder P1D, bis zu 365 Tage in die Zukunft. Die kurzen Verzögerungen, die send --at nimmt, etwa 2h, werden hier abgelehnt.
• —Seriendruckfelder funktionieren in --subject, --html und --text: {{firstName}}, {{lastName}}, {{name}}, {{email}} und {{unsubscribeUrl}}, jeweils mit einem Ersatzwert nach einem senkrechten Strich, wie in {{firstName|there}}. Ein Body, der {{unsubscribeUrl}} nicht einsetzt, bekommt eine einzeilige Abmeldezeile am Ende. Eine Vorlage wird unverändert gesendet, setzen Sie den Link also in die Vorlage.
• —Ein Broadcast wird mit den monatlichen Versänden des Tarifs abgeglichen, bevor irgendetwas geschrieben wird, und jede Kopie zählt als ein Versand. Einer, den das Kontingent nicht abdecken kann, wird mit 429 send_quota_exceeded abgelehnt, und nichts bleibt zurück.
• —Übergeben Sie Ihren eigenen --idempotency-key an broadcasts send, wenn ein Skript den Schritt erneut ausführen könnte. Derselbe Schlüssel antwortet mit dem Broadcast, den er angelegt hat, statt einen neuen zu senden.
• —Ein Kontakt, der sich von einem Broadcast abmeldet, bleibt mit gesetztem unsubscribedAt in der Zielgruppe, und spätere Broadcasts an diese Zielgruppe überspringen ihn. audiences list-contacts --statuses unsubscribed listet sie auf.
• —Ein Hard Bounce bleibt auf der Sperrliste. suppressions remove lehnt ihn mit 409 suppression_not_removable ab, und removable sagt das bei jeder Zeile im Voraus.