Autenticazione

Ogni richiesta all’API di Emailit deve contenere una credenziale nell’header Authorization. Questa pagina descrive i due tipi di credenziali (chiavi API e token di accesso OAuth), cosa consente ciascun permesso (scope) e tutti gli errori di autenticazione che puoi ricevere.

Chiavi API

Una chiave API appartiene a un solo workspace, e ogni richiesta fatta con quella chiave agisce su quel workspace. Le chiavi hanno questo aspetto:

secret_Xq7pL2mN9vB4kR8tW1yZ6cH3jF5dS0aG

Cioè secret_ seguito da 32 lettere e cifre. Le chiavi create prima del formato secret_ non hanno prefisso e continuano a funzionare.

Crea le chiavi nel pannello in Email API›API Keys, oppure con Crea una chiave API. Il secret viene mostrato una sola volta, quando crei o rigeneri la chiave, quindi salvalo subito. Per gestirle, vedi Chiavi API.

Le stesse chiavi funzionano come password SMTP per l’SMTP relay.

Invia la chiave con ogni richiesta

Usa lo schema Bearer nell’header Authorization. L’API non accetta chiavi nella query string né nel corpo della richiesta.

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

const response = await fetch('https://api.emailit.com/v2/domains', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const domains = await response.json();

import os
import requests

response = requests.get(
    "https://api.emailit.com/v2/domains",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
domains = response.json()

Gli SDK impostano questo header per te quando passi la chiave al client.

Permessi

Ogni chiave ha uno dei due permessi. Lo scegli quando crei la chiave e non puoi cambiarlo in seguito.

Una chiave sending può chiamare questi endpoint e nient’altro:

Per leggere le email (elenco, recupero, MIME grezzo, corpo, metadati, allegati e stato) serve una chiave full. Quando una chiave sending chiama qualsiasi altro endpoint, l’API restituisce 403 con Permission denied: full (o Permission denied: read per gli endpoint di lettura delle email).

Tutti gli endpoint indica il permesso di ogni endpoint.

Limita una chiave a un dominio

Una chiave sending può anche essere vincolata a un solo dominio di invio. Passa l’ID del dominio come sending_domain_id quando crei la chiave. Una chiave limitata può inviare solo da indirizzi di quel dominio. Qualsiasi altro dominio in from restituisce 403:

{
  "error": "Domain not authorized",
  "message": "API key is not authorized to send from this domain"
}

Le limitazioni per dominio valgono solo per le chiavi sending. Una chiave full ha sempre accesso a tutti i domini del workspace.

Token di accesso OAuth

Le app che agiscono per conto di un utente di Emailit, come i client MCP e le integrazioni di terze parti, non chiedono una chiave API. Usano invece OAuth 2.1: l’utente accede a Emailit, sceglie i workspace che l’app può usare (tutti o solo alcuni) e approva il permesso sending o full, e l’app riceve un token di accesso. L’utente può modificare o revocare questo accesso in App collegate.

Invia i token di accesso nello stesso header delle chiavi API:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…

Un token di accesso è valido per 15 minuti e agisce sul workspace predefinito dell’autorizzazione, con il permesso concesso e il ruolo che l’utente ha in quel workspace. Le app lo rinnovano con il token di aggiornamento (refresh token). Per crearne una, vedi App OAuth.

Errori di autenticazione

L’autenticazione viene eseguita prima di qualsiasi altra cosa, quindi questi errori possono arrivare da qualsiasi endpoint.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Permission denied: full"
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Workspace is suspended"
}

{
  "code": "unverified_workspace_recipient",
  "error": "Workspace not verified",
  "message": "Unverified workspaces can only send to workspace members' account emails. Blocked recipient: ada@example.com.",
  "blocked_recipients": ["ada@example.com"]
}

Workspace non verificati

I nuovi workspace partono non verificati. Finché Emailit non approva l’accesso alla produzione, l’API invia solo agli indirizzi email degli account dei membri del workspace. Un invio, un nuovo tentativo o un inoltro verso chiunque altro restituisce 403 con il codice unverified_workspace_recipient e l’elenco blocked_recipients, e le campagne non possono essere inviate affatto. Le chiavi API funzionano normalmente per tutto il resto.

Mantieni segrete le chiavi

Una chiave API dà accesso al workspace, quindi trattala come una password.

• Chiama l’API solo dal tuo server. Non inserire mai una chiave nel JavaScript del browser, in un’app mobile o in altro codice che gira sul dispositivo di qualcun altro.
• Tieni le chiavi fuori dal controllo di versione. Caricale da variabili d’ambiente o da un gestore di secret.
• Crea una chiave per ogni applicazione e ambiente, e dalle il nome del posto in cui la usi, così puoi revocarne una senza bloccare le altre.
• Dai a ogni chiave solo l’accesso che le serve: una chiave sending, limitata a un dominio, basta per la maggior parte delle applicazioni.
• Controlla last_used_at in Elenca le chiavi API ed elimina le chiavi che non usi più.
• Se una chiave viene esposta, rigenerala o eliminala subito. Il vecchio secret smette di funzionare immediatamente.

Vedi anche