# 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 <LA_TUA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "from": "Acme <ciao@tuodominio.dev>", "to": "sara@acme.io",
        "subject": "Benvenuta", "html": "<h1>Pronti</h1>",
        "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 <ciao@tuodominio.dev>",
    to: "sara@acme.io",
    subject: "Benvenuta",
    html: "<h1>Pronti</h1>",
    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 <a@b.com>'.
- `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.

### Domini

- `GET/POST /api/v1/domains` (scope: domains:write) - Elenca o aggiungi un dominio (ritorna i record DNS).
- `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).
- `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.

### Campagne

- `GET/POST /api/v1/campaigns` (scope: campaigns:write) - Elenca o crea una campagna broadcast.
- `GET /api/v1/campaigns/:id` (scope: campaigns:write) - Dettaglio 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_...`).
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`, `get_usage`
- **CRM**: `list_contacts`, `create_tag`, `tag_contacts`, `create_list`, `add_contacts_to_list`, `remove_contacts_from_list`, `create_segment`, `estimate_segment`, `create_custom_field`
- **Invio**: `send_email`, `send_message`, `create_campaign`, `estimate_campaign`, `send_campaign`
- **Automazioni**: `create_automation`, `activate_automation`
- **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`

## 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 <a@b.com>`. Il dominio dell'indirizzo deve essere verificato.
- **Gate d'invio**: invio consentito solo da dominio verificato; gli indirizzi in suppression (bounce/complaint/unsubscribe) vengono bloccati.
- **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.