Per sviluppatori

Costruisci su TraXmark: un'unica API REST, chiavi API con scope espliciti, errori RFC 7807 e paginazione con cursore.

Riferimento OpenAPI 3.1.0

TraXmark API v1

Intelligenza di engagement e-mail su un'unica API REST. Leggi e scrivi contatti, messaggi, eventi, documenti, buste e proposte con lo stesso formato di chiave, la stessa forma degli errori e lo stesso contratto di paginazione.

Autenticazione: una chiave API trax_…. Viene conservato solo il suo hash Argon2id.
Gli errori seguono RFC 7807 e includono una chiave i18n più l'header x-correlation-id.
Paginazione con cursore su ogni elenco, con un massimo di 100 elementi per pagina.
Anti-enumerazione: una risorsa inesistente e una risorsa senza accesso restituiscono entrambe 404.

Risorse

Sei risorse, ciascuna leggibile e scrivibile tramite scope corrispondenti.

/api/v1/contactsLettura con scope contacts:read, scrittura con scope contacts:write.

/api/v1/messagesLettura con scope messages:read, scrittura con scope messages:write.

/api/v1/eventsLettura con scope events:read, scrittura con scope events:write.

/api/v1/documentsLettura con scope documents:read, scrittura con scope documents:write.

/api/v1/envelopesLettura con scope envelopes:read, scrittura con scope envelopes:write.

/api/v1/proposalsLettura con scope proposals:read, scrittura con scope proposals:write.

Scope

Ogni chiave API viene emessa con un insieme esplicito di 16 scope.

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

Una richiesta senza lo scope richiesto viene rifiutata con 403.

Endpoint (19)

Tutte le route vivono sotto un unico URL di base e rispondono con la stessa forma di errore.

Metodo	Endpoint	Scope	Descrizione
`GET`	`/api/v1/contacts`	`contacts:read`	Restituisce una pagina di `contacts` (paginazione con cursore, limite 100).
`POST`	`/api/v1/contacts`	`contacts:write`	Crea una nuova voce di `contacts`.
`GET`	`/api/v1/contacts/{id}`	`contacts:read`	Recupera un singolo elemento `contacts` per ID. Risorsa assente o accesso negato: 404.
`GET`	`/api/v1/messages`	`messages:read`	Restituisce una pagina di `messages` (paginazione con cursore, limite 100).
`POST`	`/api/v1/messages`	`messages:write`	Crea una nuova voce di `messages`.
`GET`	`/api/v1/messages/{id}`	`messages:read`	Recupera un singolo elemento `messages` per ID. Risorsa assente o accesso negato: 404.
`GET`	`/api/v1/events`	`events:read`	Restituisce una pagina di `events` (paginazione con cursore, limite 100).
`POST`	`/api/v1/events`	`events:write`	Crea una nuova voce di `events`.
`GET`	`/api/v1/events/{id}`	`events:read`	Recupera un singolo elemento `events` per ID. Risorsa assente o accesso negato: 404.
`GET`	`/api/v1/documents`	`documents:read`	Restituisce una pagina di `documents` (paginazione con cursore, limite 100).
`POST`	`/api/v1/documents`	`documents:write`	Crea una nuova voce di `documents`.
`GET`	`/api/v1/documents/{id}`	`documents:read`	Recupera un singolo elemento `documents` per ID. Risorsa assente o accesso negato: 404.
`GET`	`/api/v1/envelopes`	`envelopes:read`	Restituisce una pagina di `envelopes` (paginazione con cursore, limite 100).
`POST`	`/api/v1/envelopes`	`envelopes:write`	Crea una nuova voce di `envelopes`.
`GET`	`/api/v1/envelopes/{id}`	`envelopes:read`	Recupera un singolo elemento `envelopes` per ID. Risorsa assente o accesso negato: 404.
`GET`	`/api/v1/proposals`	`proposals:read`	Restituisce una pagina di `proposals` (paginazione con cursore, limite 100).
`POST`	`/api/v1/proposals`	`proposals:write`	Crea una nuova voce di `proposals`.
`GET`	`/api/v1/proposals/{id}`	`proposals:read`	Recupera un singolo elemento `proposals` per ID. Risorsa assente o accesso negato: 404.
`POST`	`/api/v1/campaigns/send`	`campaigns:write`	Avvia una campagna. Consuma un'unità di `campaigns_per_month` più `messages_per_month` pari al numero di destinatari. Oltre il limite di messaggi l'API risponde 403 — a meno che il tenant abbia l'overage (`platform_config` → `overage.enabled`) e un cliente Stripe; in quel caso viene fatturato un blocco di 1000 messaggi, il limite cresce e l'invio va a buon fine.

Esempi SDK

Punti di partenza da copiare verso l'URL di base pubblico.

Node.js

fetch nativo, corpo RFC 7807 in caso di errore, cursore da 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 con raise_for_status e decodifica 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()

Sostituisci la variabile d'ambiente con una chiave emessa in Impostazioni → Chiavi API: la chiave inizia con trax_.