Diese Anleitung zeigt dir, wie du Empfänger aus deinem eigenen System über die optilyz-API an einen One-Shot sendest.

Den One-Shot legst du im optilyz-Dashboard an. Die API sendet nur Empfänger an ihn.

Bevor du anfängst

• Du hast einen One-Shot mit dem Status Wartet auf Empfänger. Dafür schließt du die Einrichtung ab und klickst auf Empfänger hinzufügen. Siehe One-Shot: Schritt-für-Schritt-Anleitung.
• Du hast einen API-Schlüssel. Du erstellst ihn selbst im Dashboard unter Einstellungen. Siehe API-Schlüssel erstellen.
• Du weißt, wie du aus deinem System HTTP-Anfragen sendest. Die optilyz-API-Referenz beschreibt alle Felder.

1. One-Shot-ID finden

Öffne deinen One-Shot im Dashboard. Der blaue Kasten unter dem Namen zeigt One-Shot-ID: …. Kopiere diese ID.

Die ID steht auch am Ende der Seitenadresse: /one-shot/<One-Shot-ID>.

Die ID erscheint erst, nachdem du auf Empfänger hinzufügen geklickt hast. Vorher ist der One-Shot ein Entwurf und kann keine Empfänger bekommen.

2. Nummern der Varianten finden

Jeder Empfänger braucht eine Variantennummer. Variante A ist 1, Variante B ist 2 und so weiter.

Auf der One-Shot-Seite zeigt der Bereich Druckdaten die Nummer jeder Variante als Varianten-ID: 1, Varianten-ID: 2. Der Einrichtungsschritt Druckdaten zeigt dieselben Nummern. Wenn dein Konto auch mit einer Marketing-Integration verbunden ist, zeigen beide nur die Buchstaben. Zähle dann ab A = 1.

3. Empfänger senden

Ein One-Shot hat keinen eigenen Endpunkt. Du nutzt den Empfänger-Endpunkt für Automatisierungen und setzt die One-Shot-ID dort ein, wo sonst die ID der Automatisierung steht:

POST https://www.optilyz.com/api/v3/automations/<One-Shot-ID>/recipients

• Sende 1 bis 2.500 Empfänger pro Anfrage. Für mehr Empfänger sendest du mehrere Anfragen.
• Sende den Header Authorization: Bearer <dein API-Schlüssel>.
• Sende den Header Content-Type: application/json.
• Jeder Empfänger braucht address und variation.
• Die Adresse braucht zipCode, city, einen Namen (lastName oder fullName, oder companyName1) und eine Straße (street mit houseNumber, oder address1). Die API-Referenz listet alle Felder, auch die Felder für die Personalisierung.

Beispiel mit einem Empfänger. Es nutzt die One-Shot-ID aus dem Bild in Schritt 1. Nutze die ID deines eigenen One-Shots:

curl -X POST "https://www.optilyz.com/api/v3/automations/6abb8ac80d6ca884758c80fc/recipients" \
  -H "Authorization: Bearer DEIN_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      {
        "address": {
          "firstName": "Erika",
          "lastName": "Musterfrau",
          "street": "Beispielstraße",
          "houseNumber": "12",
          "zipCode": "10115",
          "city": "Berlin",
          "country": "Deutschland"
        },
        "variation": 1
      }
    ]
  }'

Die Antwort bei Erfolg ist:

HTTP/1.1 201 Created
{
  "code": "RecipientReceived",
  "message": "Recipients successfully received."
}

Wenn du einen Empfänger pro Anfrage senden willst, kannst du auch den Endpunkt für einen Empfänger nutzen: POST https://www.optilyz.com/api/v3/automations/<One-Shot-ID>/recipient. Siehe Enqueue one recipient.

Details zur Authentifizierung findest du in der Einleitung der API-Referenz.

4. Prüfen, ob die Empfänger angekommen sind

Die Antwort 201 bedeutet „empfangen“. Sie bedeutet nicht „zum One-Shot hinzugefügt“. optilyz fügt die Empfänger kurz danach hinzu.

In diesen Fällen fügt optilyz die Empfänger nicht hinzu, und du bekommst keinen Fehler:

• Du hast sie gesendet, bevor du auf Empfänger hinzufügen geklickt hast.
• Du hast sie gesendet, während du den One-Shot bearbeitest (nach Bearbeiten und bevor du wieder auf Empfänger hinzufügen klickst).
• Du hast sie gesendet, nachdem du auf Buchen geklickt hast.
• Du hast eine falsche ID genutzt oder die ID eines One-Shots aus einem anderen Konto.

Prüfe deshalb nach deiner ersten Anfrage:

1. Öffne die One-Shot-Seite.
2. Sieh dir den Bereich Empfängervalidierung an. Klicke bei Bedarf auf Aktualisieren.
3. Prüfe, ob die Zahl bei … warten auf Validierung gestiegen ist.

Wenn die Zahl nicht steigt, sieh unter „Fehlerbehebung“ nach.

5. Empfänger validieren und buchen

1. Wenn alle Empfänger gesendet sind, sende keine weiteren.
2. Klicke auf Empfänger validieren.
3. Wenn die Validierung fertig ist, wähle das Postauflieferungsdatum und klicke auf Buchen.

Wenn du nach einer Validierung weitere Empfänger sendest, ist Buchen wieder gesperrt. Der Tooltip zeigt Sobald alle Empfänger validiert sind, kannst du buchen. Klicke dann wieder auf Empfänger validieren.

Die Schritt-für-Schritt-Anleitung erklärt die Validierung, den Versandzeitplan und die Buchung im Detail.

Fehlerbehebung

Gut zu wissen

• Mit der API kannst du keinen One-Shot anlegen. Lege ihn im Dashboard an. Sende dann Empfänger an ihn.
• Nachdem du auf Buchen geklickt hast, nimmt der One-Shot keine Empfänger mehr an. Sende keine Empfänger mehr, bevor du buchst.
• Bearbeiten löscht alle Empfänger, die du gesendet hast, und macht den One-Shot wieder zum Entwurf. Klicke nach dem Bearbeiten wieder auf Empfänger hinzufügen. Sende dann alle Empfänger erneut.
• Die API lehnt doppelte Empfänger nicht ab. Deine Validierungsregeln legen fest, ob Duplikate bei der Validierung entfernt werden.
• Wenn du eine Variantennummer sendest, die der One-Shot nicht hat, bekommt die Anfrage trotzdem 201. Der Empfänger zeigt nach der Validierung einen Fehler.
• Die One-Shot-Seite zeigt eine Gesamtzahl für alle Quellen. Sie zeigt keine eigene Zahl für API-Empfänger.
• Du kannst an denselben One-Shot Empfänger per API senden und auch CSV-Dateien hochladen. Siehe Empfänger aus CSV-Dateien hochladen.
• Wenn dein Konto auch mit Emarsys oder Salesforce Marketing Cloud verbunden ist und Kontakte von dort ohne Datenzuordnung warten, startet Empfänger validieren nicht. Das hält auch deine API-Empfänger auf. Siehe Empfänger aus Emarsys oder Salesforce Marketing Cloud senden.

Weitere Artikel

• One-Shot: Schritt-für-Schritt-Anleitung
• Empfänger aus CSV-Dateien hochladen
• Empfänger aus Emarsys oder Salesforce Marketing Cloud senden
• API-Schlüssel erstellen
• optilyz-API-Referenz