Riferimento REST
Tutti gli endpoint REST raggruppati per area. Base https://sending.dev/api/v1
Tutte le route sono sotto https://sending.dev/api/v1 e richiedono l'header
Authorization: Bearer sk_....
Per lo schema completo di ogni endpoint (parametri, tipi, esempi e "try it") usa la API reference interattiva (OpenAPI). La tabella qui sotto è un indice rapido.
Email e messaggi
| POST | /api/v1/emails | Invia un'email transazionale. `idempotencyKey` nel body obbligatoria (min 8 char); `from`/`replyTo` accettano 'Nome <[email protected]>'.(scope: email:send) |
| GET | /api/v1/emails/:id | Stato di un invio (metadati + timeline eventi). |
| POST | /api/v1/messages | Invio transazionale unificato email/WhatsApp/Telegram.(scope: messages:send) |
Allegati
| GET/POST | /api/v1/attachments | Elenca o carica un allegato riusabile: `content` base64 per l'upload immediato, `size` per ottenere una `uploadUrl` firmata (file grandi).(scope: email:send|inbox:send) |
| GET/DELETE | /api/v1/attachments/:id | Metadati + URL di download firmata, oppure eliminazione.(scope: email:send|inbox:send) |
| POST | /api/v1/attachments/:id/confirm | Conferma un upload firmato (allinea dimensione e Content-Type reali).(scope: email:send|inbox:send) |
Domini
| GET/POST | /api/v1/domains | Elenca o aggiungi un dominio (ritorna i record DNS).(scope: domains:write) |
| GET/PATCH | /api/v1/domains/:id | Dettaglio dominio e nome mittente di default (display name del From).(scope: domains:write) |
| POST | /api/v1/domains/:id/verify | Verifica SPF, DKIM, DMARC.(scope: domains:write) |
| POST/DELETE | /api/v1/domains/:id/inbound | Abilita o disabilita la ricezione inbound (MX) per il dominio.(scope: domains:write) |
Contatti e CRM
| GET/POST | /api/v1/contacts | Elenca o crea contatti (con attributi e campi).(scope: contacts:read|write) |
| POST/DELETE | /api/v1/contacts/:id/tags | Aggiungi o rimuovi tag a un contatto.(scope: contacts:write) |
| GET/POST | /api/v1/tags | Elenca o crea tag.(scope: contacts:write) |
| DELETE | /api/v1/tags/:id | Elimina un tag.(scope: contacts:write) |
| GET/POST | /api/v1/lists | Elenca o crea liste.(scope: contacts:write) |
| DELETE | /api/v1/lists/:id | Elimina una lista.(scope: contacts:write) |
| POST/DELETE | /api/v1/lists/:id/contacts | Aggiungi o rimuovi contatti da una lista.(scope: contacts:write) |
| GET/POST | /api/v1/segments | Elenca o crea segmenti (rule tree AudienceRules).(scope: contacts:write) |
| PATCH/DELETE | /api/v1/segments/:id | Aggiorna o elimina un segmento.(scope: contacts:write) |
| POST | /api/v1/segments/preview | Stima i contatti che matchano un segmento.(scope: contacts:read) |
| GET/POST | /api/v1/custom-fields | Elenca o crea campi personalizzati.(scope: contacts:write) |
Eventi e automazioni
| POST | /api/v1/events | Invia un evento (trigger/goal automazioni, con properties).(scope: events:write) |
| GET | /api/v1/automations | Elenca le automazioni con stato ed evento che le innesca (guardalo prima di scrivere su liste/tag).(scope: automations:read) |
| POST | /api/v1/automations | Crea un'automazione (Journey DAG) in bozza.(scope: automations:write) |
| POST | /api/v1/automations/:id/activate | Attiva un'automazione.(scope: automations:write) |
Template
| GET/POST | /api/v1/templates | Elenca o crea un template di contenuto riusabile (e' cosi' che si ottiene un templateId valido).(scope: templates:read|write) |
| GET/PATCH | /api/v1/templates/:id | Dettaglio col contenuto, oppure modifica parziale (i campi assenti restano).(scope: templates:read|write) |
| DELETE | /api/v1/templates/:id | Elimina un template: 409 se una campagna lo usa ancora.(scope: templates:write) |
Campagne
| GET/POST | /api/v1/campaigns | Elenca o crea una campagna broadcast.(scope: campaigns:write) |
| GET | /api/v1/campaigns/:id | Dettaglio campagna, contenuto incluso.(scope: campaigns:read) |
| PATCH | /api/v1/campaigns/:id | Modifica una bozza: solo i campi presenti, senza ricreare la campagna.(scope: campaigns:write) |
| POST | /api/v1/campaigns/:id/estimate | Stima i destinatari.(scope: campaigns:write) |
| POST | /api/v1/campaigns/:id/send | Invia o schedula la campagna.(scope: campaigns:write) |
| POST | /api/v1/campaigns/:id/cancel | Annulla una campagna schedulata.(scope: campaigns:write) |
Agent Email (inbox per agenti)
| GET/POST | /api/v1/inboxes | Elenca o crea una agent inbox.(scope: inbox:read|write) |
| GET/PATCH/DELETE | /api/v1/inboxes/:id | Dettaglio, aggiorna o elimina una inbox.(scope: inbox:read|write) |
| POST | /api/v1/inboxes/:id/send | Invia un'email dalla inbox.(scope: inbox:send) |
| POST | /api/v1/inboxes/:id/drafts | Crea una bozza nella inbox.(scope: inbox:write) |
| GET | /api/v1/inboxes/:id/threads | Elenca i thread della inbox.(scope: inbox:read) |
| GET | /api/v1/inboxes/:id/threads/:threadId | Dettaglio thread con messaggi.(scope: inbox:read) |
| POST | /api/v1/inboxes/:id/threads/:threadId/reply | Rispondi a un thread.(scope: inbox:send) |
| GET | /api/v1/inboxes/metrics | Metriche agent email (volumi, consegna, bounce).(scope: inbox:read) |
Webhooks
| GET/POST | /api/v1/webhooks | Elenca o crea un endpoint webhook (secret one-time).(scope: webhooks:read|write) |
| GET/PATCH/DELETE | /api/v1/webhooks/:id | Dettaglio, aggiorna o elimina un webhook.(scope: webhooks:read|write) |
| GET | /api/v1/webhooks/:id/deliveries | Log delle consegne di un webhook.(scope: webhooks:read) |
Allow/Block (regole inbound)
| GET/POST | /api/v1/email-rules | Elenca o crea regole allow/block per le inbox.(scope: inbox:read|write) |
| DELETE | /api/v1/email-rules/:id | Elimina una regola allow/block.(scope: inbox:write) |
UTM e attribuzione
| GET | /api/v1/utm/touches | Touch UTM (con ?format=csv).(scope: utm:read) |
| GET | /api/v1/utm/conversions | Conversioni attribuite (first/last).(scope: utm:read) |
| GET | /api/v1/utm/summary | Riepilogo attribuzione.(scope: utm:read) |
Integrazioni e usage
| POST | /api/v1/integrations/posthog/sync | Lancia il sync delle conversioni da PostHog.(scope: integrations:write) |
| GET | /api/v1/usage | Snapshot uso vs piano del workspace. |
Limiti di frequenza
Ogni API key può fare 10 richieste al secondo. Il conteggio è per chiave, non per workspace: due integrazioni dello stesso workspace hanno budget separati, così una impazzita non spegne le altre.
Ogni risposta porta lo stato corrente:
| Header | Significato |
|---|---|
RateLimit-Limit | Richieste consentite nella finestra. |
RateLimit-Remaining | Quante ne restano. |
RateLimit-Reset | Secondi al reset della finestra. |
Oltre il limite la risposta è 429 con Retry-After in secondi e corpo
{ "error": "rate_limit_exceeded", "limit": 10, "retryAfter": 1 }. Rispetta Retry-After e
aggiungi un backoff esponenziale con jitter sui tentativi successivi.
Una chiamata a POST /api/v1/emails/batch conta una richiesta, quali
che siano i suoi 100 elementi: è il modo previsto per mandare molte email senza avvicinarsi
al limite.
Cosa non è un limite di frequenza
- Quota del piano: il numero di messaggi al mese è un'altra cosa e risponde
402o403, non429. Dove l'overage è attivo, oltre l'incluso si fattura a consumo. - Velocità di uscita verso SES: gli invii accettati passano da una coda che manda circa
14 messaggi al secondo complessivi. Un batch accettato in un secondo può impiegare più di
un secondo a partire davvero:
202e207significano "preso in carico", non "già spedito".