Riferimento API

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:

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 e imposta EMAILIT_API_KEY su una delle tue chiavi API.

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>"
  }'

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>',
});

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 per tutte le opzioni.

Autenticazione

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

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.

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 e Filtri e ordinamento.
• Errori. Le richieste non riuscite restituiscono un codice di stato 4xx o 5xx e un corpo JSON che spiega il problema. Vedi Errori.

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.

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.

Risorse

Per una tabella unica con tutti gli endpoint e il permesso che ciascuno richiede, vedi Tutti gli endpoint.

SDK

Le librerie ufficiali incapsulano l’API per i linguaggi più diffusi. Sono open source su GitHub.

Webhook ed eventi

Invece di interrogare l’API per conoscere i cambi di stato, registra un webhook 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. Vedi Tipi di evento 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 e il riferimento degli strumenti.

Vedi anche