Voraussetzung für den Versand von Postkarten über die EchtPost API ist, dass Sie neben einem API-Schlüssel eine Vorlage innerhalb Ihres EchtPost-Accounts angelegt haben. Aufgrund der unterschiedlichen Zeichenbeschränkungen je nach Schriftart ist es nicht möglich, eine Postkarte mit einem jeweils individuellen Text über die API anzulegen.
Hinweis: Wenn Sie nicht über Programmierkenntnisse verfügen, können Sie mit dennoch mit Hilfe von Zapier Verknüpfungen zwischen EchtPost und anderen Software Tools herstellen.
Den API-Schlüssel erstellen Sie innerhalb Ihres EchtPost-Accounts in den Account Einstellungen (Zahnrad rechts oben) und dann unter "API-Schlüssel zum Datenaustausch".
Eine Vorlage für Ihre Postkarte erstellen Sie, indem Sie beginnen eine Postkarte zu schreiben. Dort wählen Sie zunächst ein Motiv aus und schreiben einen Grußtext auf die Rückseite. Um eine individuelle Anrede für die jeweils angeschriebenen Empfänger einzusetzen, können Sie {Anrede} als Platzhalter einsetzen. Dieser Platzhalter wird bei der Erstellung der Karte gegen Ihre voreingestellte Anrede (Account Einstellungen > "Mein Konto" > "Standard-Anrede für Postkarten festlegen") ersetzt. Im Anschluss speichern Sie die Vorlage.
Über "Vorlagen" finden Sie im Anschluss die individuelle ID Ihrer erstellten Vorlage.
Für den Versand der Vorlage benötigen Sie dann nur einen Aufruf per JSON an unseren POST-Endpunkt. Sie haben dabei verschiedene Möglichkeiten, um den oder die Empfänger zu setzen. Die Grundstruktur des JSON-Aufrufs und ein Beispiel in Ruby on Rails sieht dabei exemplarisch wie folgt aus:
json_hash = {
apikey: 'your-echtpost-api-key',
card: {
template_id: integer_id,
deliver_at: '2024-03-15',
notification_type: 'before_send', # optional; can also be 'after_send'
notification_date: '2024-03-10', # optional
notification_email: 'your-email@example.com', # optional
contacts_attributes: [
{
company_name: 'EchtPost',
first: 'Anne',
name: 'Buch',
street: 'Marktstr 10 - Gebäude E8',
zip: '50968,
city: 'Köln',
country_code: 'DE'
}
]
}
}
RestClient::Request.execute(
url: 'https://api.echtpost.de/v1/cards',
method: :post,
headers: { content_type: 'application/json' },
payload: json_hash.to_json,
verify_ssl: false
)Im Folgenden finden Sie weitere Beispiele mit Curl:
curl --location 'https://api.echtpost.de/v1/cards?apikey=your-echtpost-api-key' \
--header 'Content-Type: application/json' \
--data '{"card":{"template_id":"TEMPLATE_ID","deliver_at":"2025-11-19","contacts_attributes":[{"title":"Prof.","company_name":"Sample KG","first":"Anne","name":"Buch","street":"Marktstrasse 10 - E8","zip":"50968","city":"Köln","country_code":"DE"}]}}'curl --location 'https://api.echtpost.de/v1/cards?apikey=your-echtpost-api-key' \
--header 'Content-Type: application/json' \
--data '{"card":{"template_id":"TEMPLATE_ID","deliver_at":"2023-11-29","contact_id":"CONTACT_ID"}}'Versand an einen Kontakt mit Kontaktdaten
Um die Kontaktdaten direkt zu übergeben und den Kontakt nicht zuerst im EchtPost Adressbuch anlegen zu müssen, nutzen Sie den contact_attributes Parameter, wie in dem vorangehenden Beispiel.
Versand an einen bestehenden EchtPost-Empfänger
Wenn der gewünschte Empfänger bereits als Kontakt in Ihrem EchtPost-Account angelegt ist, dann können Sie die ID des Kontaktes über den Parameter contact_id übergeben. Der Parameter contacts_attributes entfällt in diesem Fall.
Versand an mehrere bestehende EchtPost-Empfänger
Um die Vorlage an mehrere Empfänger aus dem EchtPost Adressbuch zu versenden, übergeben Sie einen Array mit den gewünschten Contact IDs über den Parameter contact_ids. Der Parameter contacts_attributes entfällt in diesem Fall.
Versand an die Kontakte einer Gruppe
Über den Parameter group_id können Sie die ID einer EchtPost Empfängergruppe übergeben. Die ID dieser Gruppe finden Sie in der URL, sobald Sie die Gruppe auf der Empfänger-Übersicht anwählen.
Fehlercodes
400 Bad Request: Wenn falsche Daten wie eine ungültige template_id, contact_id oä übergeben werden, antwortet die API mit 400 BadRequest und gibt weitere Details zurück, wie zB das fehlerhafte Feld im Contact.
402 Payment Required: Wenn das vorhandene Guthaben in Ihrem Account nicht ausreicht, antwortet die API mit 402 Payment Required.
Sandbox-Modus
Durch Übergabe des Parameters sandbox=1 wird die Validierung der Daten regulär durchgeführt und der Request auch normal beantwortet, aber die Karte wird am Ende nicht erstellt, sondern verworfen.