# Integrare Sending (REST + MCP) Sending e un orchestratore di messaggistica multicanale (email su Amazon SES, WhatsApp, Telegram) con API REST e tool MCP per agenti AI. Usa questo documento come riferimento completo. ## Base URL e autenticazione - Base URL: `https://sending.dev` - REST: tutte le route sotto `https://sending.dev/api/v1` - MCP: endpoint streamable HTTP su `https://sending.dev/api/mcp` - Auth: header `Authorization: Bearer sk_...` (API key creata nella dashboard, sezione API Keys). Il workspace (tenant) e SEMPRE derivato dal token, mai da un parametro. - Scope: ogni chiave porta scope granulari (es. `email:send`, `contacts:write`, `inbox:send`, `webhooks:write`, `automations:write`) oppure `*` (full access). ## Quickstart: invia un'email curl: ```bash curl -X POST "https://sending.dev/api/v1/emails" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "from": "Acme ", "to": "sara@acme.io", "subject": "Benvenuta", "html": "

Pronti

", "idempotencyKey": "welcome-sara-001" }' ``` TypeScript (fetch, nessun SDK richiesto): ```ts await fetch("https://sending.dev/api/v1/emails", { method: "POST", headers: { "authorization": `Bearer ${process.env.SENDING_API_KEY}`, "content-type": "application/json", }, body: JSON.stringify({ from: "Acme ", to: "sara@acme.io", subject: "Benvenuta", html: "

Pronti

", idempotencyKey: crypto.randomUUID(), }), }) ``` ## Riferimento REST ### Email e messaggi - `POST /api/v1/emails` (scope: email:send) - Invia un'email transazionale. `idempotencyKey` nel body obbligatoria (min 8 char); `from`/`replyTo` accettano 'Nome '. - `GET /api/v1/emails/:id` - Stato di un invio (metadati + timeline eventi). - `POST /api/v1/messages` (scope: messages:send) - Invio transazionale unificato email/WhatsApp/Telegram. ### Allegati - `GET/POST /api/v1/attachments` (scope: email:send|inbox:send) - Elenca o carica un allegato riusabile: `content` base64 per l'upload immediato, `size` per ottenere una `uploadUrl` firmata (file grandi). - `GET/DELETE /api/v1/attachments/:id` (scope: email:send|inbox:send) - Metadati + URL di download firmata, oppure eliminazione. - `POST /api/v1/attachments/:id/confirm` (scope: email:send|inbox:send) - Conferma un upload firmato (allinea dimensione e Content-Type reali). ### Domini - `GET/POST /api/v1/domains` (scope: domains:write) - Elenca o aggiungi un dominio (ritorna i record DNS). - `GET/PATCH /api/v1/domains/:id` (scope: domains:write) - Dettaglio dominio e nome mittente di default (display name del From). - `POST /api/v1/domains/:id/verify` (scope: domains:write) - Verifica SPF, DKIM, DMARC. - `POST/DELETE /api/v1/domains/:id/inbound` (scope: domains:write) - Abilita o disabilita la ricezione inbound (MX) per il dominio. ### Contatti e CRM - `GET/POST /api/v1/contacts` (scope: contacts:read|write) - Elenca o crea contatti (con attributi e campi). - `POST/DELETE /api/v1/contacts/:id/tags` (scope: contacts:write) - Aggiungi o rimuovi tag a un contatto. - `GET/POST /api/v1/tags` (scope: contacts:write) - Elenca o crea tag. - `DELETE /api/v1/tags/:id` (scope: contacts:write) - Elimina un tag. - `GET/POST /api/v1/lists` (scope: contacts:write) - Elenca o crea liste. - `DELETE /api/v1/lists/:id` (scope: contacts:write) - Elimina una lista. - `POST/DELETE /api/v1/lists/:id/contacts` (scope: contacts:write) - Aggiungi o rimuovi contatti da una lista. - `GET/POST /api/v1/segments` (scope: contacts:write) - Elenca o crea segmenti (rule tree AudienceRules). - `PATCH/DELETE /api/v1/segments/:id` (scope: contacts:write) - Aggiorna o elimina un segmento. - `POST /api/v1/segments/preview` (scope: contacts:read) - Stima i contatti che matchano un segmento. - `GET/POST /api/v1/custom-fields` (scope: contacts:write) - Elenca o crea campi personalizzati. ### Eventi e automazioni - `POST /api/v1/events` (scope: events:write) - Invia un evento (trigger/goal automazioni, con properties). - `GET /api/v1/automations` (scope: automations:read) - Elenca le automazioni con stato ed evento che le innesca (guardalo prima di scrivere su liste/tag). - `POST /api/v1/automations` (scope: automations:write) - Crea un'automazione (Journey DAG) in bozza. - `POST /api/v1/automations/:id/activate` (scope: automations:write) - Attiva un'automazione. ### Template - `GET/POST /api/v1/templates` (scope: templates:read|write) - Elenca o crea un template di contenuto riusabile (e' cosi' che si ottiene un templateId valido). - `GET/PATCH /api/v1/templates/:id` (scope: templates:read|write) - Dettaglio col contenuto, oppure modifica parziale (i campi assenti restano). - `DELETE /api/v1/templates/:id` (scope: templates:write) - Elimina un template: 409 se una campagna lo usa ancora. ### Campagne - `GET/POST /api/v1/campaigns` (scope: campaigns:write) - Elenca o crea una campagna broadcast. - `GET /api/v1/campaigns/:id` (scope: campaigns:read) - Dettaglio campagna, contenuto incluso. - `PATCH /api/v1/campaigns/:id` (scope: campaigns:write) - Modifica una bozza: solo i campi presenti, senza ricreare la campagna. - `POST /api/v1/campaigns/:id/estimate` (scope: campaigns:write) - Stima i destinatari. - `POST /api/v1/campaigns/:id/send` (scope: campaigns:write) - Invia o schedula la campagna. - `POST /api/v1/campaigns/:id/cancel` (scope: campaigns:write) - Annulla una campagna schedulata. ### Agent Email (inbox per agenti) - `GET/POST /api/v1/inboxes` (scope: inbox:read|write) - Elenca o crea una agent inbox. - `GET/PATCH/DELETE /api/v1/inboxes/:id` (scope: inbox:read|write) - Dettaglio, aggiorna o elimina una inbox. - `POST /api/v1/inboxes/:id/send` (scope: inbox:send) - Invia un'email dalla inbox. - `POST /api/v1/inboxes/:id/drafts` (scope: inbox:write) - Crea una bozza nella inbox. - `GET /api/v1/inboxes/:id/threads` (scope: inbox:read) - Elenca i thread della inbox. - `GET /api/v1/inboxes/:id/threads/:threadId` (scope: inbox:read) - Dettaglio thread con messaggi. - `POST /api/v1/inboxes/:id/threads/:threadId/reply` (scope: inbox:send) - Rispondi a un thread. - `GET /api/v1/inboxes/metrics` (scope: inbox:read) - Metriche agent email (volumi, consegna, bounce). ### Webhooks - `GET/POST /api/v1/webhooks` (scope: webhooks:read|write) - Elenca o crea un endpoint webhook (secret one-time). - `GET/PATCH/DELETE /api/v1/webhooks/:id` (scope: webhooks:read|write) - Dettaglio, aggiorna o elimina un webhook. - `GET /api/v1/webhooks/:id/deliveries` (scope: webhooks:read) - Log delle consegne di un webhook. ### Allow/Block (regole inbound) - `GET/POST /api/v1/email-rules` (scope: inbox:read|write) - Elenca o crea regole allow/block per le inbox. - `DELETE /api/v1/email-rules/:id` (scope: inbox:write) - Elimina una regola allow/block. ### UTM e attribuzione - `GET /api/v1/utm/touches` (scope: utm:read) - Touch UTM (con ?format=csv). - `GET /api/v1/utm/conversions` (scope: utm:read) - Conversioni attribuite (first/last). - `GET /api/v1/utm/summary` (scope: utm:read) - Riepilogo attribuzione. ### Integrazioni e usage - `POST /api/v1/integrations/posthog/sync` (scope: integrations:write) - Lancia il sync delle conversioni da PostHog. - `GET /api/v1/usage` - Snapshot uso vs piano del workspace. ## MCP per agenti AI Endpoint: `https://sending.dev/api/mcp` (streamable HTTP). Auth: stesso bearer token (`Authorization: Bearer sk_...`). Il server e remoto: non esiste un pacchetto npm da installare e non c'e un endpoint SSE. Per collegarlo a un client (guida completa: `https://sending.dev/docs/mcp/clients`): - Claude Code: `claude mcp add --transport http sending https://sending.dev/api/mcp --header "Authorization: Bearer sk_..."` - Client con file `mcpServers` (Cursor, e `.mcp.json` di Claude Code, che vuole anche `"type": "http"`): voce con `"url": "https://sending.dev/api/mcp"` e `"headers": { "Authorization": "Bearer sk_..." }` - VS Code: stessa forma ma sotto la chiave `servers`, con `"type": "http"` - ChatGPT (developer mode) e i connettori di claude.ai/Claude Desktop: solo l'URL, senza header; l'autenticazione e OAuth 2.1 e i permessi si scelgono nella schermata di consenso - Client solo stdio: ponte `npx -y mcp-remote https://sending.dev/api/mcp --header "Authorization: Bearer sk_..."` I tool destructive (invio reale) hanno guardrail server-side: cap di volume/spesa giornaliero, audit log e scope per chiave. Tool disponibili: - **Domini e usage**: `list_domains`, `verify_domain`, `set_domain_sender_name`, `get_usage`, `set_frequency_cap` - **CRM**: `list_contacts`, `upsert_contact`, `list_tags`, `create_tag`, `update_tag`, `delete_tag`, `tag_contacts`, `list_lists`, `create_list`, `update_list`, `delete_list`, `add_contacts_to_list`, `remove_contacts_from_list`, `list_segments`, `create_segment`, `estimate_segment`, `create_custom_field` - **Template**: `list_templates`, `get_template`, `create_template`, `update_template` - **Invio**: `send_email`, `send_message`, `list_campaigns`, `get_campaign`, `get_campaign_metrics`, `create_campaign`, `update_campaign`, `estimate_campaign`, `send_campaign` - **Allegati e immagini**: `upload_attachment`, `list_attachments`, `delete_attachment`, `upload_image`, `list_images` - **Automazioni**: `list_automations`, `get_automation`, `create_automation`, `update_automation`, `activate_automation`, `enroll_contacts`, `test_automation`, `get_automation_log`, `get_automation_stats` - **Agent Email**: `list_inboxes`, `create_inbox`, `list_threads`, `get_thread`, `send_from_inbox`, `reply_thread`, `get_agent_email_metrics` - **Webhooks e regole**: `list_webhooks`, `create_webhook`, `delete_webhook`, `list_email_rules`, `create_email_rule`, `delete_email_rule` - **Attribuzione**: `get_utm_summary`, `list_utm_touches`, `list_utm_conversions`, `get_contact_conversions`, `get_contact_journey`, `get_conversion_stats` - **Import**: `connect_activecampaign`, `start_activecampaign_import`, `get_import_status` ## Convenzioni - **Idempotenza**: passa `idempotencyKey` nel body (obbligatoria sugli invii email, min 8 caratteri) per evitare duplicati sui retry. Non esiste un header `Idempotency-Key`. - **Mittente**: `from` (e `replyTo`) accettano sia `a@b.com` sia `Nome `. Il dominio dell'indirizzo deve essere verificato. - **Allegati**: campo `attachments` su email transazionali, messaggi, campagne e invii dalle inbox agente. Ogni elemento indica UNA sorgente: `{ id }` (allegato caricato con `POST /api/v1/attachments`, riusabile), `{ filename, content }` (base64 inline, per file piccoli) oppure `{ filename, url }` (https pubblica). Con `contentId` l'allegato diventa inline e si referenzia nell'HTML come `cid:`. Limiti: max 20 allegati, 10 MB l'uno, 25 MB complessivi; estensioni eseguibili rifiutate. - **Gate d'invio**: invio consentito solo da dominio verificato; gli indirizzi in suppression (bounce/complaint/unsubscribe) vengono bloccati. - **Disiscrizione**: non serve costruire il link a mano. `{{unsubscribe_url}}` nell'HTML viene sostituito con il link firmato del destinatario su **tutti** i percorsi d'invio (transazionale, campagne, automazioni, Agent Email). Nelle campagne, se il segnaposto non c'e' aggiungiamo noi un footer "Annulla iscrizione" e in ogni caso gli header `List-Unsubscribe` one-click; sui transazionali il link c'e' solo se lo scrivi tu, ed e' una soppressione vera per quell'indirizzo. - **Effetti collaterali**: aggiungere un contatto a una lista o applicare un tag emette un evento (`contact.list_added`, `contact.tag_added`) che puo' far partire un'automazione, quindi invii reali. `GET /api/v1/automations` e il tool `list_automations` dicono quali sono attive e su quale evento. - **Automazioni**: un Journey e' un DAG di nodi (`id`, `type`, archi verso altri id o `null`). Oltre a `message` e `webhook` ci sono azioni sul contatto (`add_tag`, `remove_tag`, `subscribe`, `unsubscribe`, `update_contact`, `add_note`, `score`, `conversion`) e di flusso (`wait` a durata/data/condizione, `branch`, `split` pesato, `goto`, `start_automation`, `end_automation`, `goal`, `exit`): l'elenco completo con i campi sta nella descrizione di `create_automation`. Serve esattamente un trigger, e i cicli sono ammessi solo passando da un `goto`. Per correggerne una gia' creata usa `get_automation` + `update_automation`, non ricrearla da zero. - **Provare prima di attivare**: `test_automation` fa passare UN contatto dentro il flusso con le attese compresse, anche su una bozza. I messaggi partono davvero verso quel contatto, quindi usa un indirizzo tuo; il passaggio di prova non occupa lo slot "una sola iscrizione per contatto". - **Capire cosa e' successo**: `get_automation_log` elenca i passi attraversati dai contatti con l'esito. Uno stato `skipped` non e' un errore: dice cosa ha fermato quel passo (suppression, quota, risorsa mancante), ed e' la risposta a "perche' questo contatto non ha ricevuto l'email". `get_automation_stats` da' lo stesso quadro per nodo invece che per contatto: a quale passo il flusso perde le persone. - **Misurare gli invii**: `get_campaign_metrics` (e il campo `metrics` di `get_campaign` e `list_campaigns`) porta consegne, aperture e click unici, disiscrizioni, bounce e reclami. Le aperture contano solo eventi umani: Apple MPP e i proxy aprono da soli, quindi confronta le campagne sui **click**, non sull'open rate. Mandare senza leggere l'esito e' il modo piu' rapido di ripetere una campagna che non aveva funzionato. - **Errori**: risposte JSON `{ "error": "..." }`; codici tipici 401 (no auth), 403 (scope mancante), 409 (conflitto/suppression/duplicato), 422 (input non valido), 402 (limite di piano raggiunto). - **Entitlement**: i limiti dipendono dal piano del workspace; `GET /api/v1/usage` ne da lo snapshot.

Prompt for AI agents

Prompt pronto per il tuo agente