Panoramica per sviluppatori

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

Non sai se usare l’API o SMTP? Leggi API o SMTP.

URL di base e versioni

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

https://api.emailit.com/v2

v2 è la versione attuale e l’unica documentata. L’API v1 legacy è deprecata; vedi Versionamento.

Autenticazione

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

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.
• I token di accesso OAuth emessi per le app OAuth 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.

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.

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.
• 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.
• 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.
• 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.
• 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 e Limiti e quote.

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. Per i comandi di installazione vedi SDK e librerie, e per esempi completi le guide per framework, a partire da Node.js.

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 e Firma delle richieste.

Server MCP e strumenti AI

Il server 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 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 le indicizza tutte.

Passaggi successivi