# Panoramica per sviluppatori

> URL di base, autenticazione, ID degli oggetti, errori, paginazione, limiti di frequenza, SDK, webhook e MCP. Le convenzioni comuni a ogni integrazione con Emailit.

Questa pagina raccoglie le convenzioni da conoscere prima di scrivere codice per Emailit: dove si trova l’API, come vengono autenticate le richieste, come vengono identificati gli oggetti e come funzionano errori, paginazione e limiti di frequenza. Ogni sezione rimanda al riferimento dettagliato.

## Modi di integrazione

| Interfaccia | Endpoint | A cosa serve |
| --- | --- | --- |
| API REST | `https://api.emailit.com/v2` | Inviare email e gestire ogni risorsa dal codice. |
| SMTP relay | `smtp.emailit.com` | App, framework e CMS che usano già SMTP. Vedi [Impostazioni SMTP](/it/docs/smtp/settings/). |
| Webhook | Il tuo endpoint HTTPS | Eventi in tempo reale su consegne, engagement e risorse. |
| Server MCP | `https://api.emailit.com/mcp` | Permettere ad assistenti AI come Claude, ChatGPT e Cursor di lavorare con il tuo workspace. |
| OAuth 2.1 | `https://api.emailit.com/oauth/*` | Integrazioni che agiscono per conto degli utenti di Emailit senza gestire le loro chiavi API. |

Non sai se usare l’API o SMTP? Leggi [API o SMTP](/it/docs/get-started/api-or-smtp/).

## URL di base e versioni

Tutti gli endpoint REST si trovano sotto un unico URL di base:

```text
https://api.emailit.com/v2
```

`v2` è la versione attuale e l’unica documentata. L’API `v1` legacy è deprecata; vedi [Versionamento](/it/docs/api-reference/versioning/).

## Autenticazione

Invia una chiave API come token Bearer nell’header `Authorization` di ogni richiesta:

```bash
curl https://api.emailit.com/v2/domains \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

- Le chiavi API iniziano con `secret_`. Le chiavi meno recenti senza prefisso continuano a funzionare.
- Ogni chiave appartiene a un workspace e ha un permesso: **Full Access** (`full`) può chiamare ogni endpoint, **Sending Only** (`sending`) può solo inviare e gestire gli invii. Vedi [Chiavi API](/it/docs/developers/api-keys/).
- I token di accesso OAuth emessi per le [app OAuth](/it/docs/developers/oauth-apps/) sono accettati nello stesso header.
- Una chiave mancante restituisce `401` con `API key required`, una chiave sconosciuta restituisce `401` con `Invalid API key` e un workspace sospeso restituisce `403` con `Workspace is suspended`.

Non chiamare mai l’API con la tua chiave da un browser o da un’app mobile. Tienila sul server. Dettagli: [Autenticazione](/it/docs/api-reference/authentication/).

## ID e prefissi

Ogni oggetto ha un ID stringa con un prefisso di tipo, così capisci a colpo d’occhio a cosa si riferisce un ID.

| Oggetto | Prefisso | Esempio |
| --- | --- | --- |
| Email | `em_` | `em_4K6oASS7KP9ztzWmSN9ndEu13HW` |
| Dominio di invio | `dom_` | `dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6` |
| Chiave API | `key_` | `key_4F2kN8sQwE1rT6yU3iO9pA7sD5f` |
| Lista | `aud_` | `aud_3zR8tY2uI6oP4aS1dF9gH7jK5lM` |
| Iscritto | `sub_` | `sub_4K6oASS7KP9ztzWnqS4svxApJzO` |
| Contatto | `con_` | `con_4A9sD2fG6hJ1kL8zX3cV7bN5mQw` |
| Template | `tem_` | `tem_3wE8rT1yU5iO9pA2sD6fG4hJ7kL` |
| Soppressione | `sup_` | `sup_4K6oASS7KP9ztzWol5ElicOeKFE` |
| Webhook | `wh_` | `wh_3mN7bV2cX6zL9kJ4hG1fD8sA5pO` |
| Richiesta webhook | `whr_` | `whr_4K6oASS7KP9ztzWpVUIec9Jneax` |
| Evento | `evt_` | `evt_4K6oASS7KP9ztzWpqId2iIptac5` |
| Campagna | `cmp_` | `cmp_4B1nM5qW9eR3tY7uI2oP6aS8dF4` |
| Modulo | `frm_` | `frm_4C3vB7nM1qW5eR9tY2uI6oP8aS4` |
| Risposta a un modulo | `fsub_` | `fsub_4K6oASS7KP9ztzWqvxLV3IsFRs8` |
| Automazione | `aut_` | `aut_4D5fG9hJ3kL7zX1cV6bN2mQ8wE4` |
| Esecuzione di un’automazione | `aur_` | `aur_4K6oASS7KP9ztzWrWOjGgqompRo` |
| Verifica email | `ev_` | `ev_4E7gH1jK5lZ9xC3vB8nM2qW6eR4` |
| Lista di verifica | `evl_` | `evl_4F9hJ3kL7zX1cV5bN9mQ2wE6rT8` |
| Report DMARC | `dmr_` | `dmr_4K6oASS7KP9ztzWsW7e5qkOYHO6` |

I domini creati prima del passaggio agli ID `dom_` possono avere ancora ID `sd_` o `sed_`.

Alcuni endpoint accettano anche un identificatore leggibile al posto dell’ID: un nome per chiavi API, domini, webhook, campagne e liste, e un indirizzo email per contatti e soppressioni. Email, template ed eventi si cercano solo per ID.

## Richieste e risposte

- **JSON in ingresso, JSON in uscita.** Invia i corpi delle richieste come JSON con `Content-Type: application/json`. Un JSON non valido restituisce `400` con `Invalid JSON in request body`. Il corpo di una richiesta può arrivare a 50 MB; il messaggio MIME finale di un’email può arrivare a 40 MB.
- **Errori.** La maggior parte degli errori restituisce `{"statusCode", "error", "message"}`. Gli errori di convalida aggiungono un array `details`, e gli errori di invio restituiscono `validation_errors`. Le funzioni riservate a determinati piani restituiscono `403` con `"error": "plan_required"`. Vedi [Errori](/it/docs/api-reference/errors/).
- **Paginazione.** Gli endpoint di elenco accettano `page` e `limit` (da 1 a 100) e restituiscono `data`, `next_page_url` e `previous_page_url`. Template e automazioni usano `page` e `per_page`. Vedi [Paginazione](/it/docs/api-reference/pagination/).
- **Filtri e ordinamento.** Filtra con `field.condition=value`, combina i filtri con `match=all` o `match=or` e ordina con `order` e `direction`. Ad esempio, `GET /v2/emails?status.exact=bounced&order=created_at&direction=desc`. Vedi [Filtri e ordinamento](/it/docs/api-reference/filtering/).
- **Idempotenza.** Invia un header `Idempotency-Key` con `POST /emails` e `POST /emails/:id/forward` per rendere sicuri i nuovi tentativi. Emailit ripropone la prima risposta per 24 ore. Vedi [Idempotenza](/it/docs/api-reference/idempotency/).
- **Limiti di frequenza.** L’invio è limitato per workspace, per impostazione predefinita a 2 email al secondo e 5000 email al giorno, condivisi tra API e SMTP. Le risposte includono gli header `ratelimit-*`, e una risposta `429` include `retry-after`. Vedi [Limiti di frequenza](/it/docs/api-reference/rate-limits/) e [Limiti e quote](/it/docs/limits/).

## SDK

Le librerie ufficiali incapsulano l’API REST per Node.js, PHP, Laravel, Python, Ruby, Go, Java, .NET e Rust. Si trovano tutte su [GitHub](https://github.com/emailit). Per i comandi di installazione vedi [SDK e librerie](/it/docs/sdks/), e per esempi completi le guide per framework, a partire da [Node.js](/it/docs/frameworks/nodejs/).

## Webhook

I webhook inviano gli eventi al tuo endpoint man mano che accadono: consegne, bounce, aperture, clic, email in entrata e modifiche a domini, contatti e altre risorse. Ogni richiesta contiene un array JSON di massimo 100 eventi ed è firmata con HMAC-SHA256 nell’header `X-Emailit-Signature`. Le richieste non riuscite vengono ritentate per un massimo di 11 tentativi. Inizia da [Configura un webhook](/it/docs/webhooks/set-up/) e [Firma delle richieste](/it/docs/webhooks/request-signature/).

## Server MCP e strumenti AI

Il [server MCP](/it/docs/mcp/) ospitato su `https://api.emailit.com/mcp` offre agli assistenti AI 109 strumenti che coprono l’intera API v2, dall’invio di email a campagne e automazioni. Gli assistenti accedono con OAuth o con una chiave API, e i [plugin di Emailit](/it/docs/mcp/plugins-and-skills/) aggiungono skill per ChatGPT, Codex, Claude Code, Cursor e Grok.

La documentazione è pubblicata anche per l’AI: ogni pagina ha una versione Markdown e [/docs/llms.txt](/it/docs/developers/llms-txt/) le indicizza tutte.

## Passaggi successivi

  - [Crea una chiave API](/it/docs/developers/api-keys/): Scegli un permesso, limitala a un dominio e conservala in modo sicuro.
  - [Invia la prima email](/it/docs/quickstart/api/): Fai la prima chiamata API in pochi minuti.
  - [SDK e librerie](/it/docs/sdks/): Librerie ufficiali per nove linguaggi e framework.
  - [Riferimento API](/it/docs/api-reference/): Ogni endpoint, parametro e risposta.

---
Fonte: https://emailit.com/it/docs/developers/