# Riferimento API

> L’API REST di Emailit in breve. URL di base, autenticazione, richieste e risposte JSON, ID degli oggetti, controllo delle versioni e tutte le risorse che puoi gestire.

L’API di Emailit è un’API REST servita via HTTPS. Invii JSON, ricevi JSON e autentichi ogni richiesta con un token Bearer. Usala per inviare email e per gestire tutto il resto di un workspace: domini di invio, chiavi API, contatti, liste, campagne, template, webhook e altro ancora.

## URL di base

Ogni richiesta va all’URL di base della versione 2:

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

I percorsi di questo riferimento sono relativi a questo URL. Ad esempio, `POST /emails` significa `POST https://api.emailit.com/v2/emails`.

## Fai la prima richiesta

Questa richiesta invia un’email. Sostituisci il mittente con un indirizzo di un [dominio di invio verificato](/it/docs/domains/verification/) e imposta `EMAILIT_API_KEY` su una delle tue [chiavi API](/it/docs/developers/api-keys/).

**cURL**

```bash
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Welcome to Acme",
    "html": "<p>Thanks for signing up.</p>"
  }'
```

**Node.js**

```javascript
import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);

const email = await emailit.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'ada@example.com',
  subject: 'Welcome to Acme',
  html: '<p>Thanks for signing up.</p>',
});
```

**Python**

```python
import os
from emailit import EmailitClient

client = EmailitClient(os.environ["EMAILIT_API_KEY"])

email = client.emails.send({
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Welcome to Acme",
    "html": "<p>Thanks for signing up.</p>",
})
```

La risposta è il nuovo oggetto email, con il suo ID (`em_…`) e lo stato `accepted`. Vedi [Invia un’email](/it/docs/api-reference/emails/send/) per tutte le opzioni.

## Autenticazione

Passa una chiave API o un token di accesso OAuth nell’header `Authorization`:

```http
Authorization: Bearer secret_••••••••••••••••••••••••••••••••
```

Le chiavi API iniziano con `secret_` e appartengono a un solo workspace. Una chiave ha il permesso `full` (tutti gli endpoint) o il permesso `sending` (solo gli endpoint di invio), e una chiave di solo invio può essere limitata a un dominio di invio. Le richieste senza una chiave valida non riescono e restituiscono `401`. Vedi [Autenticazione](/it/docs/api-reference/authentication/).

## Richieste e risposte

- **JSON in entrata, JSON in uscita.** Invia il corpo delle richieste in JSON con `Content-Type: application/json`. Un corpo che non è JSON valido restituisce `400` con il messaggio `Invalid JSON in request body`. Il corpo di una richiesta può arrivare al massimo a 50 MB.
- **Metodi.** `GET` legge, `POST` crea e aggiorna, `DELETE` elimina. L’API non usa `PUT` né `PATCH`.
- **Oggetti.** Ogni oggetto ha un campo `object` che ne indica il tipo (`email`, `domain`, `api_key`, `audience`, `subscriber`, `contact`, …) e un `id`.
- **Timestamp.** Le date sono stringhe ISO 8601 in UTC con precisione al microsecondo, ad esempio `2026-10-01T09:30:12.482913Z`. I campi non impostati valgono `null`.
- **Elenchi.** Gli endpoint che restituiscono elenchi sono paginati e la maggior parte accetta filtri e ordinamento. Vedi [Paginazione](/it/docs/api-reference/pagination/) e [Filtri e ordinamento](/it/docs/api-reference/filtering/).
- **Errori.** Le richieste non riuscite restituiscono un codice di stato `4xx` o `5xx` e un corpo JSON che spiega il problema. Vedi [Errori](/it/docs/api-reference/errors/).

## ID degli oggetti

Gli ID sono stringhe composte da un prefisso che indica il tipo e da 27 lettere e cifre, ad esempio `em_4KYof1ZzXndZE2VPi0DgULiekG8`. Gli ID distinguono tra maiuscole e minuscole e seguono all’incirca l’ordine di creazione.

| Prefisso | Oggetto | Prefisso | Oggetto |
| --- | --- | --- | --- |
| `em_` | Email | `aud_` | Lista |
| `dom_` | Dominio di invio | `sub_` | Iscritto |
| `key_` | Chiave API | `con_` | Contatto |
| `tem_` | Template | `cmp_` | Campagna |
| `sup_` | Soppressione | `frm_` | Modulo |
| `wh_` | Webhook | `fsub_` | Risposta a un modulo |
| `whr_` | Richiesta webhook | `aut_` | Automazione |
| `evt_` | Evento | `aur_` | Esecuzione di un’automazione |
| `dmr_` | Report DMARC | `ev_` | Verifica email |
| `evl_` | Lista di verifica | | |

Alcune risorse accettano nel percorso anche un identificativo leggibile. Domini, chiavi API, liste, campagne e webhook accettano il loro nome (`GET /domains/acme.com`). Contatti e soppressioni accettano un indirizzo email, e gli iscritti accettano l’indirizzo email del contatto. Codifica per l’URL i nomi e gli indirizzi che contengono caratteri speciali. I domini creati prima del passaggio agli ID `dom_` mantengono il loro ID `sd_` o `sed_`, e questi ID funzionano ancora.

## Controllo delle versioni

La versione attuale è `v2` e fa parte dell’URL di base. Nuovi campi ed endpoint vengono aggiunti a `v2` senza cambiare versione, quindi scrivi client che ignorano i campi che non riconoscono. Vedi [Controllo delle versioni](/it/docs/api-reference/versioning/).

## Risorse

  - [Email](/it/docs/api-reference/emails/): Invia email, leggi i messaggi e il loro contenuto, e programmali, annullali, ritentali o inoltrali.
  - [Domini](/it/docs/api-reference/domains/): Aggiungi domini di invio, leggi i loro record DNS e verificali.
  - [Report DMARC](/it/docs/api-reference/dmarc/): Leggi i report DMARC aggregati e forensi di un dominio, o carica i tuoi.
  - [Chiavi API](/it/docs/api-reference/api-keys/): Crea, rinomina, rigenera ed elimina le chiavi API di un workspace.
  - [Liste](/it/docs/api-reference/audiences/): Gestisci le liste di iscritti usate dalle campagne e dai moduli di iscrizione.
  - [Iscritti](/it/docs/api-reference/audiences/subscribers/): Aggiungi, aggiorna e rimuovi gli iscritti di una lista.
  - [Contatti](/it/docs/api-reference/contacts/): Gestisci i profili dei contatti e i campi personalizzati, uno alla volta o in blocco.
  - [Campagne](/it/docs/api-reference/campaigns/): Crea campagne, scegli le loro liste e inviale o programmale.
  - [Automazioni](/it/docs/api-reference/automations/): Costruisci flussi di lavoro con trigger e passaggi, eseguili e analizza le loro esecuzioni.
  - [Moduli](/it/docs/api-reference/forms/): Crea moduli di iscrizione, pubblicali e ruota il loro token pubblico.
  - [Template](/it/docs/api-reference/templates/): Crea versioni dei template, pubblicane una per alias e usala per inviare.
  - [Soppressioni](/it/docs/api-reference/suppressions/): Leggi e gestisci gli indirizzi a cui Emailit non invia.
  - [Webhook](/it/docs/api-reference/webhooks/): Registra endpoint che ricevono notifiche di eventi firmate.
  - [Eventi](/it/docs/api-reference/events/): Leggi il flusso di eventi alla base dei webhook: consegne, bounce, aperture e altro.
  - [Verifica email](/it/docs/api-reference/email-verifications/): Verifica un singolo indirizzo in tempo reale.
  - [Liste di verifica](/it/docs/api-reference/email-verifications/lists/): Verifica fino a 10.000 indirizzi alla volta ed esporta gli esiti.

Per una tabella unica con tutti gli endpoint e il permesso che ciascuno richiede, vedi [Tutti gli endpoint](/it/docs/api-reference/endpoints/).

## SDK

Le librerie ufficiali incapsulano l’API per i linguaggi più diffusi. Sono open source su [GitHub](https://github.com/emailit).

| Linguaggio | Pacchetto | Guida |
| --- | --- | --- |
| Node.js | `@emailit/node` | [Node.js](/it/docs/frameworks/nodejs/) |
| Python | `emailit` | [Python](/it/docs/frameworks/python/) |
| PHP | `emailit/emailit-php` | [PHP](/it/docs/frameworks/php/) |
| Laravel | `emailit/emailit-laravel` | [Laravel](/it/docs/frameworks/laravel/) |
| Ruby | `emailit` | [Ruby on Rails](/it/docs/frameworks/rails/) |
| Go | `github.com/emailit/emailit-go/v2` | [Go](/it/docs/frameworks/go/) |
| Java | `com.emailit` | [Java](/it/docs/frameworks/java/) |
| .NET | `Emailit` | [.NET](/it/docs/frameworks/dotnet/) |
| Rust | `emailit` | [SDK](/it/docs/sdks/) |

## Webhook ed eventi

Invece di interrogare l’API per conoscere i cambi di stato, registra un [webhook](/it/docs/webhooks/) ed Emailit invierà al tuo endpoint batch firmati di eventi man mano che si verificano: consegne, bounce, aperture, clic, nuovi contatti e altro. Gli stessi eventi sono disponibili con [Elenca gli eventi](/it/docs/api-reference/events/list/). Vedi [Tipi di evento](/it/docs/webhooks/event-types/) per l’elenco completo.

## Server MCP

Il server MCP ospitato su `https://api.emailit.com/mcp` permette agli assistenti AI come ChatGPT, Claude, Cursor, Codex e Grok di chiamare questa API per conto tuo: 109 strumenti coprono tutte le risorse di questa pagina. Gli assistenti accedono con OAuth o usano una chiave API, con gli stessi permessi. Vedi [Server MCP di Emailit](/it/docs/mcp/) e il [riferimento degli strumenti](/it/docs/mcp/tools/).

## Vedi anche

  - [Autenticazione](/it/docs/api-reference/authentication/): Chiavi API, permessi, limitazioni per dominio e token OAuth.
  - [Limiti di frequenza](/it/docs/api-reference/rate-limits/): Limiti di invio, header delle risposte e come applicare il backoff.
  - [Errori](/it/docs/api-reference/errors/): Formati degli errori, codici di stato e soluzioni comuni.
  - [Invia la prima email con l’API](/it/docs/quickstart/api/): Un avvio rapido passo passo, dalla chiave API all’inbox.

---
Fonte: https://emailit.com/it/docs/api-reference/