Für Entwickler

Bauen Sie auf TraXmark: eine REST-Oberfläche, API-Schlüssel mit expliziten Scopes, RFC-7807-Fehler und Cursor-Paginierung.

OpenAPI-3.1.0-Referenz

TraXmark API v1

E-Mail-Engagement-Intelligenz über eine einzige REST-Oberfläche. Kontakte, Nachrichten, Ereignisse, Dokumente, Umschläge und Angebote lesen und schreiben — mit identischem Key-Format, Fehlerformat und Paginierungsvertrag.

Authentifizierung: ein trax_…-API-Key. Gespeichert wird ausschließlich dessen Argon2id-Hash.
Fehler folgen RFC 7807 und tragen einen i18n-Key sowie den Header x-correlation-id.
Cursor-Paginierung auf jeder Liste, begrenzt auf 100 Einträge pro Seite.
Enumerationsschutz: Eine nicht existierende Ressource und eine Ressource ohne Zugriff liefern beide 404.

Ressourcen

Sechs Ressourcen, jeweils lesbar und schreibbar über passende Scopes.

/api/v1/contactsLesen mit Scope contacts:read, Schreiben mit Scope contacts:write.

/api/v1/messagesLesen mit Scope messages:read, Schreiben mit Scope messages:write.

/api/v1/eventsLesen mit Scope events:read, Schreiben mit Scope events:write.

/api/v1/documentsLesen mit Scope documents:read, Schreiben mit Scope documents:write.

/api/v1/envelopesLesen mit Scope envelopes:read, Schreiben mit Scope envelopes:write.

/api/v1/proposalsLesen mit Scope proposals:read, Schreiben mit Scope proposals:write.

Scopes

Jeder API-Key wird mit einem expliziten Satz von 16 Scopes ausgestellt.

campaigns:read

campaigns:write

contacts:read

contacts:write

messages:read

messages:write

events:read

events:write

documents:read

documents:write

envelopes:read

envelopes:write

proposals:read

proposals:write

devices:read

devices:write

Eine Anfrage ohne den erforderlichen Scope wird mit 403 abgelehnt.

Endpunkte (19)

Alle Routen laufen unter einer Basis-URL und antworten mit derselben Fehlerstruktur.

Methode	Endpunkt	Scope	Beschreibung
`GET`	`/api/v1/contacts`	`contacts:read`	Gibt eine Seite von `contacts` zurück (Cursor-Paginierung, max. 100).
`POST`	`/api/v1/contacts`	`contacts:write`	Erstellt einen neuen `contacts`-Eintrag.
`GET`	`/api/v1/contacts/{id}`	`contacts:read`	Ruft ein einzelnes `contacts`-Element per ID ab. Existiert es nicht oder fehlt der Zugriff, kommt 404.
`GET`	`/api/v1/messages`	`messages:read`	Gibt eine Seite von `messages` zurück (Cursor-Paginierung, max. 100).
`POST`	`/api/v1/messages`	`messages:write`	Erstellt einen neuen `messages`-Eintrag.
`GET`	`/api/v1/messages/{id}`	`messages:read`	Ruft ein einzelnes `messages`-Element per ID ab. Existiert es nicht oder fehlt der Zugriff, kommt 404.
`GET`	`/api/v1/events`	`events:read`	Gibt eine Seite von `events` zurück (Cursor-Paginierung, max. 100).
`POST`	`/api/v1/events`	`events:write`	Erstellt einen neuen `events`-Eintrag.
`GET`	`/api/v1/events/{id}`	`events:read`	Ruft ein einzelnes `events`-Element per ID ab. Existiert es nicht oder fehlt der Zugriff, kommt 404.
`GET`	`/api/v1/documents`	`documents:read`	Gibt eine Seite von `documents` zurück (Cursor-Paginierung, max. 100).
`POST`	`/api/v1/documents`	`documents:write`	Erstellt einen neuen `documents`-Eintrag.
`GET`	`/api/v1/documents/{id}`	`documents:read`	Ruft ein einzelnes `documents`-Element per ID ab. Existiert es nicht oder fehlt der Zugriff, kommt 404.
`GET`	`/api/v1/envelopes`	`envelopes:read`	Gibt eine Seite von `envelopes` zurück (Cursor-Paginierung, max. 100).
`POST`	`/api/v1/envelopes`	`envelopes:write`	Erstellt einen neuen `envelopes`-Eintrag.
`GET`	`/api/v1/envelopes/{id}`	`envelopes:read`	Ruft ein einzelnes `envelopes`-Element per ID ab. Existiert es nicht oder fehlt der Zugriff, kommt 404.
`GET`	`/api/v1/proposals`	`proposals:read`	Gibt eine Seite von `proposals` zurück (Cursor-Paginierung, max. 100).
`POST`	`/api/v1/proposals`	`proposals:write`	Erstellt einen neuen `proposals`-Eintrag.
`GET`	`/api/v1/proposals/{id}`	`proposals:read`	Ruft ein einzelnes `proposals`-Element per ID ab. Existiert es nicht oder fehlt der Zugriff, kommt 404.
`POST`	`/api/v1/campaigns/send`	`campaigns:write`	Startet eine Kampagne. Verbraucht eine Einheit aus `campaigns_per_month` plus `messages_per_month` in Höhe der Empfängerzahl. Über dem Nachrichtenlimit antwortet die API mit 403 — außer der Mandant hat Overage (`platform_config` → `overage.enabled`) und einen Stripe-Kunden; dann wird ein Block von 1.000 Nachrichten berechnet, das Limit wächst und der Versand läuft durch.

SDK-Beispiele

Startpunkte zum Kopieren — gegen die öffentliche Basis-URL.

Node.js

Natives fetch, RFC-7807-Body im Fehlerfall, Cursor aus nextCursor.

const res = await fetch('https://api.traxmark.com/api/v1/contacts?limit=50', {
  headers: { Authorization: `Bearer ${process.env.TRAXMARK_API_KEY}` },
});
if (!res.ok) throw new Error(await res.text()); // RFC7807 JSON
const { items, nextCursor } = await res.json();

Python

requests mit raise_for_status und JSON-Dekodierung.

import requests
r = requests.get('https://api.traxmark.com/api/v1/contacts',
                 headers={'Authorization': f'Bearer {API_KEY}'}, params={'limit': 50})
r.raise_for_status(); data = r.json()

Ersetzen Sie die Umgebungsvariable durch einen Key aus Einstellungen → API-Keys; er beginnt mit trax_.