Pour les développeurs

Construisez sur TraXmark : une seule surface REST, des clés API à scopes explicites, des erreurs RFC 7807 et une pagination par curseur.

Référence OpenAPI 3.1.0

API v1 TraXmark

L'intelligence d'engagement e-mail sur une seule surface REST. Lisez et écrivez contacts, messages, événements, documents, enveloppes et propositions avec le même format de clé, la même forme d'erreur et le même contrat de pagination.

Authentification : une clé API trax_…. Seul son hachage Argon2id est stocké.
Les erreurs suivent la RFC 7807 et portent une clé i18n ainsi que l'en-tête x-correlation-id.
Pagination par curseur sur toutes les listes, plafonnée à 100 éléments par page.
Anti-énumération : une ressource qui n'existe pas et une ressource à laquelle vous n'avez pas accès renvoient toutes deux 404.

Ressources

Six ressources, chacune lisible et accessible en écriture via des scopes correspondants.

/api/v1/contactsLecture avec le scope contacts:read, écriture avec le scope contacts:write.

/api/v1/messagesLecture avec le scope messages:read, écriture avec le scope messages:write.

/api/v1/eventsLecture avec le scope events:read, écriture avec le scope events:write.

/api/v1/documentsLecture avec le scope documents:read, écriture avec le scope documents:write.

/api/v1/envelopesLecture avec le scope envelopes:read, écriture avec le scope envelopes:write.

/api/v1/proposalsLecture avec le scope proposals:read, écriture avec le scope proposals:write.

Scopes

Chaque clé API est émise avec un ensemble explicite de 16 scopes.

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

Une requête sans le scope requis est rejetée avec un 403.

Points de terminaison (19)

Toutes les routes sont regroupées sous une seule URL de base et répondent avec la même forme d'erreur.

Méthode	Endpoint	Scope	Description
`GET`	`/api/v1/contacts`	`contacts:read`	Renvoie une page de `contacts` (pagination par curseur, plafond 100).
`POST`	`/api/v1/contacts`	`contacts:write`	Crée une nouvelle entrée `contacts`.
`GET`	`/api/v1/contacts/{id}`	`contacts:read`	Récupère un seul élément `contacts` par ID. Ressource absente ou accès refusé : les deux renvoient 404.
`GET`	`/api/v1/messages`	`messages:read`	Renvoie une page de `messages` (pagination par curseur, plafond 100).
`POST`	`/api/v1/messages`	`messages:write`	Crée une nouvelle entrée `messages`.
`GET`	`/api/v1/messages/{id}`	`messages:read`	Récupère un seul élément `messages` par ID. Ressource absente ou accès refusé : les deux renvoient 404.
`GET`	`/api/v1/events`	`events:read`	Renvoie une page de `events` (pagination par curseur, plafond 100).
`POST`	`/api/v1/events`	`events:write`	Crée une nouvelle entrée `events`.
`GET`	`/api/v1/events/{id}`	`events:read`	Récupère un seul élément `events` par ID. Ressource absente ou accès refusé : les deux renvoient 404.
`GET`	`/api/v1/documents`	`documents:read`	Renvoie une page de `documents` (pagination par curseur, plafond 100).
`POST`	`/api/v1/documents`	`documents:write`	Crée une nouvelle entrée `documents`.
`GET`	`/api/v1/documents/{id}`	`documents:read`	Récupère un seul élément `documents` par ID. Ressource absente ou accès refusé : les deux renvoient 404.
`GET`	`/api/v1/envelopes`	`envelopes:read`	Renvoie une page de `envelopes` (pagination par curseur, plafond 100).
`POST`	`/api/v1/envelopes`	`envelopes:write`	Crée une nouvelle entrée `envelopes`.
`GET`	`/api/v1/envelopes/{id}`	`envelopes:read`	Récupère un seul élément `envelopes` par ID. Ressource absente ou accès refusé : les deux renvoient 404.
`GET`	`/api/v1/proposals`	`proposals:read`	Renvoie une page de `proposals` (pagination par curseur, plafond 100).
`POST`	`/api/v1/proposals`	`proposals:write`	Crée une nouvelle entrée `proposals`.
`GET`	`/api/v1/proposals/{id}`	`proposals:read`	Récupère un seul élément `proposals` par ID. Ressource absente ou accès refusé : les deux renvoient 404.
`POST`	`/api/v1/campaigns/send`	`campaigns:write`	Démarre une campagne. Consomme une unité de `campaigns_per_month` plus `messages_per_month` égal au nombre de destinataires. Au-delà de la limite de messages, l'API répond 403 — sauf si le tenant dispose du dépassement (`platform_config` → `overage.enabled`) et d'un client Stripe ; alors un bloc de 1 000 messages est facturé, la limite augmente et l'envoi passe.

Extraits SDK

Points de départ à copier-coller, vers l'URL de base publique.

Node.js

fetch natif, corps RFC 7807 en cas d'échec, curseur via 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 avec raise_for_status et décodage JSON.

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()

Remplacez la variable d'environnement par une clé émise dans Paramètres → Clés API ; elle commence par trax_.