REST reference
Every REST endpoint grouped by area. Base https://sending.dev/api/v1
Every route lives under https://sending.dev/api/v1 and requires the
Authorization: Bearer sk_... header.
For the full schema of each endpoint (parameters, types, examples and a "try it" console) use the interactive API reference (OpenAPI). The table below is a quick index.
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. |
Rate limits
Each API key gets 10 requests per second. The count is per key, not per workspace: two integrations in the same workspace have separate budgets, so a runaway one cannot take the others down.
Every response carries the current state:
| Header | Meaning |
|---|---|
RateLimit-Limit | Requests allowed in the window. |
RateLimit-Remaining | How many are left. |
RateLimit-Reset | Seconds until the window resets. |
Past the limit the response is 429 with Retry-After in seconds and a body of
{ "error": "rate_limit_exceeded", "limit": 10, "retryAfter": 1 }. Honour Retry-After and
add exponential backoff with jitter on further attempts.
One call to POST /api/v1/emails/batch counts as one request, whatever
its 100 items contain: it is the intended way to send a lot of email without going near the
limit.
What is not a rate limit
- Plan quota: the number of messages per month is a different thing and answers
402or403, not429. Where overage is enabled, anything past the included allowance is billed on usage. - Outbound throughput to SES: accepted sends go through a queue that pushes roughly 14
messages per second overall. A batch accepted in one second can take more than a second to
actually leave:
202and207mean "accepted", not "already sent".