Panoramica della API REST TrekMail per sviluppatori
Scopri come funziona la API REST di TrekMail: autenticazione con token bearer, accesso per piano, limiti di frequenza e formati di risposta.
Dettagli dell'articolo
Tipo, difficoltà, piani e data dell'ultimo aggiornamento.
▼
Dettagli dell'articolo
Tipo, difficoltà, piani e data dell'ultimo aggiornamento.
- Tipo
- Riferimento
- Difficoltà
- Intermedio
- Piani
- Nano · Starter · Pro · Agency
- Ultimo aggiornamento
- 23 ago 2026
La API TrekMail consente di gestire domini, caselle di posta, inoltro, DNS, migrazioni email e operazioni webmail da un client HTTP o un agente AI. Sono incluse lettura e invio della posta, bozze, pianificazione, cartelle, contatti, calendari, identità, modelli e mittenti bloccati. Le richieste autenticate usano un token bearer, le risposte sono in JSON e le attività della API vengono registrate.
Cosa ottieni
- API REST v1 con formato di richiesta e risposta JSON.
- Autenticazione con token bearer: nessun cookie o sessione per le chiamate API autenticate.
- Chiavi di idempotenza nelle operazioni di scrittura che le richiedono, per evitare attività duplicate durante i nuovi tentativi.
- Limite di frequenza per token con header
Retry-After. - Registro di audit visibile nella dashboard in AI Agents & API → Audit Log.
- Server MCP con un catalogo filtrato in base a credenziale, trasporto e impostazioni di sicurezza della connessione corrente. Una connessione limitata a un progetto vede quindi solo gli strumenti che può usare.
- Alias di dominio: collega indirizzi di sola ricezione su un dominio secondario alle stesse parti locali di un dominio principale, con stati di consegna salvati rispetto a quelli attivi e rimozione sicura. Consulta Alias di dominio tramite API e MCP.
- Architettura a doppio token: token operativi distinti per l'infrastruttura e token di messaggistica per operazioni email complete, come lettura, invio, bozze, pianificazione, contatti, calendari, identità, modelli e cartelle.
- Informazioni su consegna in uscita e bounce: recupera dalla dashboard il riepilogo di messaggi inviati, consegnati, hard bounce e soft bounce, oltre ai codici e alle risposte SMTP per destinatario. Consulta Consegna e bounce.
- Utilizzo dello spazio delle caselle di posta:
list_mailboxeseget_mailboxrestituisconoused_mb,quota_mb,allocation_mbeis_pooled, così un agente può individuare le caselle prossime al limite senza accedere alla dashboard. - Amministrazione White Label: controlla la configurazione, gestisci il branding per dominio, invita clienti, controlla ruoli e domini, sospendi o ripristina l'accesso e consulta le attività tramite API o MCP. Consulta la guida al branding e la guida alla gestione dei team.
API Drive e automazione dei file
Drive fa parte della superficie API pubblica. Include gli spazi Drive dell'account e delle caselle di posta, l'utilizzo, la navigazione nelle cartelle, i caricamenti, la gestione di file e cartelle, il Cestino, le azioni in blocco, i link di condivisione pubblici, la gestione delle password dei dispositivi di sincronizzazione e lo stato di sola lettura del componente aggiuntivo Drive Storage.
Drive usa undici ambiti per token operativo: drive:account:read, drive:account:write, drive:account:share, drive:account:purge, drive:mailbox:read, drive:mailbox:write, drive:mailbox:share, drive:mailbox:purge, drive:addon:read, drive:devices:read e drive:devices:write. Le operazioni di fatturazione per il componente aggiuntivo Drive, acquisto, ridimensionamento e annullamento, restano disponibili solo nella dashboard e non sono esposte come operazioni di scrittura API o MCP.
Inizia con la Panoramica della API Drive o la Guida rapida alla API Drive.
Architettura a doppio token
La API usa due tipi di token indipendenti. Puoi usarne uno o entrambi in base alle tue esigenze:
| Tipo di token | Prefisso | Cosa abilita |
|---|---|---|
| Token operativo | tm_live_ |
Strumenti per account e infrastruttura: White Label, domini, DNS, caselle di posta, inviti, Drive, migrazioni, SMTP, ticket, fatturazione e Cloudflare |
| Token di messaggistica | tm_msg_ |
Operazioni webmail: messaggi, cartelle, allegati, bozze, invio pianificato, segnalazione spam/ham, azioni in blocco, contatti, gruppi di contatti, calendario, strumenti di composizione, identità, modelli e mittenti bloccati |
I token operativi e quelli di messaggistica hanno ambiti e limiti di frequenza distinti. Un singolo agente può usare entrambi i token contemporaneamente configurandoli nell'ambiente del server MCP.
I token di messaggistica sono disponibili con i piani Pro e Agency.
Prima di iniziare
- Tutti i piani includono l'accesso alla API:
- Nano: Email Verifier. Aggiungi il componente aggiuntivo Drive Storage per l'accesso completo alla API Drive e a MCP.
- Starter: accesso completo a Drive ed Email Verifier e accesso di sola lettura alle altre aree dell'infrastruttura. Usa la dashboard per le relative operazioni di scrittura.
- Pro / Agency: accesso completo alla API di base, inclusi i token di messaggistica. Gli ambiti White Label vengono aggiunti quando è attiva la prova o il componente aggiuntivo a pagamento.
- Vuoi collegare un agente AI? Aggiungi
https://trekmail.net/mcpcome server MCP remoto in qualsiasi client compatibile. Se supporta l'autorizzazione tramite browser, non serve alcun token manuale. Consulta Collegare agenti AI (MCP) per le opzioni remote, CLI/desktop, bridge e self-hosted. - Vuoi creare la tua integrazione? Crea un token
tm_live_in AI Agents & API → Tokens → Create token e invialo comeAuthorization: Bearer …. Consulta Creare e gestire token API. - Non conosci ancora la API? Fai clic su Start tour nella parte superiore della pagina AI Agents & API per una breve guida ai metodi di connessione, alla gestione dei token, alle applicazioni connesse e al registro di audit.
Come funziona l'autenticazione
Ogni richiesta deve includere il token nell'header Authorization:
Authorization: Bearer tm_live_abc123...
I token operativi iniziano con tm_live_ e quelli di messaggistica con tm_msg_. Entrambi vengono mostrati una sola volta al momento della creazione e non possono essere visualizzati di nuovo.
Se il token è assente, revocato o scaduto, la API restituisce 401 con il codice di errore unauthenticated.
URL di base e gestione delle versioni
Tutti gli endpoint si trovano sotto:
https://trekmail.net/api/v1
L'URL di base è mostrato nella dashboard AI Agents & API, sotto Quick Reference. La versione è indicata nel percorso dell'URL. Quando verrà introdotta una v2, se accadrà, v1 continuerà a funzionare.
Formato delle risposte
Le risposte riuscite restituiscono JSON con una chiave data per singole risorse o un elenco impaginato:
{
"data": [
{ "id": 1, "domain": "example.com", "status": "active" }
],
"links": { "next": "...", "prev": null },
"meta": { "current_page": 1, "last_page": 1, "total": 1 }
}
Le risposte di errore seguono una struttura coerente:
{
"error": {
"code": "unauthenticated",
"message": "Invalid or expired API token",
"hint": "Check that your token is correct and has not been revoked.",
"request_id": "req_abc123",
"retryable": false
}
}
ID delle richieste
Ogni risposta include un header X-Request-Id. Puoi anche specificarne uno tramite X-Request-Id nella richiesta. Verrà restituito e registrato nella traccia di audit.
Limiti di frequenza
Ogni token è soggetto a un limite di frequenza al minuto. Quando raggiungi il limite, la API restituisce 429 con un header Retry-After che indica quando puoi riprovare.
Le operazioni distruttive (intenzioni di eliminazione) hanno un ulteriore limite giornaliero per token e un periodo di attesa tra eliminazioni consecutive.
Le operazioni di scrittura per le migrazioni (avvio, annullamento, nuovo tentativo) hanno un limite dedicato di 10 richieste al minuto per token, oltre a un limite di concorrenza valido per tutto il server che restituisce 503 quando sono in esecuzione troppe migrazioni a livello globale.
I token di messaggistica usano limiti separati. I valori predefiniti sono 30 richieste di lettura al minuto per token, 60 richieste di invio al minuto per token, 5,000 letture riuscite al giorno per token e 100 invii API al giorno per singola casella di posta. Un secondo contatore di sicurezza per gli invii ha un valore predefinito di 500 per token al giorno; normalmente si applica prima il limite inferiore della casella. Queste protezioni della API non sostituiscono i limiti SMTP gestiti del piano né quelli del provider esterno.
Idempotenza
Gli endpoint che modificano lo stato e sono contrassegnati come idempotenti richiedono un header Idempotency-Key. Questo vale per creazioni, aggiornamenti, invii ed eliminazioni per cui un nuovo tentativo automatico potrebbe altrimenti duplicare l'operazione. Le azioni POST simili a letture, come il rilevamento del provider o un test di connessione, non ne richiedono uno; controlla la tabella degli endpoint o la specifica OpenAPI. Se invii la stessa chiave con lo stesso corpo, la API riproduce la risposta originale senza creare duplicati.
Idempotency-Key: create-mailbox-alice-2024
Se invii la stessa chiave con un corpo diverso, la API restituisce 409 Conflict.
Allocazione dello spazio delle caselle di posta
Ogni endpoint che crea una casella di posta o un invito, POST /api/v1/mailboxes, /api/v1/mailboxes:bulk, /api/v1/mailboxes/invites, /api/v1/mailboxes/invites:bulk, accetta un numero intero facoltativo storage_allocation_mb.
| Valore | Significato |
|---|---|
Omesso (o null) |
La casella usa il pool condiviso dell'account (impostazione predefinita). |
| Numero intero positivo (MB) | La casella è dedicata. La quantità esatta viene riservata dal pool dell'account esclusivamente per questa casella. |
Le allocazioni vengono convalidate rispetto al pool attivo, meno le caselle dedicate esistenti e gli inviti dedicati in sospeso. Gli endpoint in blocco convalidano inoltre la somma delle allocazioni dell'intero gruppo e rifiutano tutto il gruppo con 422 storage_pool_exceeded se causerebbe un'allocazione eccessiva. Il pool si aggiorna quando una casella dedicata viene eliminata, quando un invito viene riscattato (l'allocazione passa alla nuova casella) e quando un invito in sospeso scade.
Per gli inviti, l'allocazione viene registrata nel codice di accesso e copiata nella nuova casella al momento del riscatto. Se il pool non è più sufficiente per l'allocazione richiesta al momento del riscatto (per esempio, nel frattempo un altro amministratore ha aumentato la propria allocazione dedicata), il riscatto esegue un passaggio controllato della nuova casella al pool condiviso invece di non riuscire; il destinatario visualizza un avviso nella pagina di conferma.
Accesso a Drive per le caselle di posta
Ogni casella di posta ha un livello drive_access che determina a quali funzioni di Drive può accedere la persona che la usa nella webmail. Viene restituito nella risorsa casella e può essere impostato con PATCH /api/v1/mailboxes/{id} oppure, per più caselle contemporaneamente, con POST /api/v1/mailboxes:drive-access.
| Valore | Significato |
|---|---|
full |
Tutto: la scheda Drive, caricamento e condivisione, ricerca dei file e sincronizzazione con un computer. È il valore predefinito. |
attachments_only |
Nessun Drive nella webmail e nessuna sincronizzazione. L'invio continua a funzionare: un file che supera la soglia degli allegati viene inviato come link di download e la copia viene eliminata al termine del periodo di conservazione. |
disabled |
Nessun Drive e un file che supera la soglia non può essere allegato. |
Lo spazio è condiviso nell'intero account, quindi questo controllo determina quanta parte del pool una singola persona può riempire con i file.
Sospensione dell'accesso alla casella di posta
L'accesso a una casella può essere sospeso mentre continua a ricevere posta: webmail, IMAP, SMTP e password dei dispositivi vengono rifiutati e le sessioni aperte terminano, ma la consegna non viene modificata, quindi nessun messaggio genera un bounce e tutto resta in attesa del ripristino dell'accesso. Impostalo con POST /api/v1/mailboxes/{id}:suspend-login (e :resume-login) oppure, per più caselle, con POST /api/v1/mailboxes:login-access.
La risorsa casella lo segnala come login_suspended, login_suspended_at e login_suspended_reason. Leggi login_suspended per sapere se la persona può accedere e status per sapere se la casella è operativa: una casella sospesa resta active, perché continua ad accettare posta. :pause è un'altra operazione: imposta status su disabled e interrompe anche la consegna.
Consulta Sospendere l'accesso alla casella tramite API.
L'endpoint in blocco accetta esattamente un selettore tra mailbox_ids, domain_id e all e restituisce le operazioni eseguite:
{ "data": { "drive_access": "attachments_only", "matched": 24, "updated": 21, "skipped_shared": 3 } }
domain_id è il selettore da usare quando un dominio corrisponde a un cliente. Le caselle già impostate sul livello richiesto vengono conteggiate in matched ma non in updated, quindi la chiamata può essere ripetuta in sicurezza.
Le caselle condivise vengono rifiutate sull'endpoint singolo con 422 drive_access_not_applicable e ignorate, ma conteggiate, da quello in blocco: non hanno un proprio utente webmail, quindi i membri le aprono con il proprio livello e un valore memorizzato nella riga condivisa non cambierebbe nulla.
La limitazione si applica alla API e all'interfaccia. Lo spazio Drive di una casella con restrizioni non compare in GET /api/v1/drive/spaces, i relativi file restituiscono 404 in base all'ID e non è possibile creare un dispositivo di sincronizzazione per la casella.
Indirizzi di inoltro
GET /api/v1/domains/{id}/forwarding-addresses restituisce più di un semplice elenco, perché due caratteristiche di un indirizzo di inoltro non sono visibili nell'indirizzo stesso:
{
"data": [ { "id": 8, "address": "sales@acme.com", "local_part": "sales",
"domain_id": 4, "recipients": ["team@example.net"], "is_active": true } ],
"limits": { "used": 1, "max": 100, "recipients_per_address": 15 },
"delivery": { "active": true, "requires_plan": "pro",
"paused_until": null, "paused_reason": null }
}
limits.maxè per dominio e dipende dal piano: 100 per Pro, 300 per Agency e 25 salvati ma inattivi per Nano o Starter.delivery.activeindica se queste regole stanno trasferendo posta in questo momento. Èfalsecon un piano inferiore arequires_planed èfalsementre è impostatopaused_until(l'account ha superato la frequenza oraria di invio; consulta Limiti di invio per piano). Una regola può essereis_active: truesenza eseguire consegne, quindi leggidelivery, non solois_active, prima di dichiarare che l'inoltro funziona.
La creazione con un piano che non consente la consegna è permessa e restituisce 201: la regola viene salvata e inizia a funzionare dopo l'upgrade. Questo comportamento corrisponde alla dashboard, che mostra tali regole come salvate e inattive.
I rifiuti vengono restituiti con 422 e error.code impostato su validation_error o limit_exceeded: le cause possono essere un indirizzo già in uso sul dominio, un destinatario nello stesso dominio (che creerebbe un loop), un dominio destinatario senza un MX funzionante o il raggiungimento del limite per dominio.
Le operazioni POST e DELETE su questi endpoint richiedono un Idempotency-Key; PATCH non lo richiede.
Cronologia delle consegne
GET /api/v1/domains/{id}/forwarding-addresses/{addressId}/log restituisce ciò che è realmente accaduto alla posta recente, a partire dagli eventi più nuovi:
{
"data": [
{ "id": 91, "occurred_at": "2026-07-27T09:12:04+00:00", "outcome": "delivered",
"from": "rfq@northgatesupply.com", "to": "sales@example.net",
"smtp_code": "2.0.0", "smtp_response": "250 2.0.0 OK" }
],
"address": "sales@acme.com",
"window": { "retention_days": 30, "max_events": 200 }
}
outcome può essere delivered, deferred (errore temporaneo, nuovi tentativi ancora in corso), failed (il server del destinatario ha rifiutato il messaggio) o blocked; quest'ultimo significa che il nostro filtro antispam ha bloccato il messaggio prima dell'inoltro, quindi non ha mai raggiunto il destinatario. Considerare blocked come un bounce porterebbe a indagare sul server di ricezione per un problema che si è verificato sul nostro.
limit (1-200, valore predefinito 100) è l'unico parametro. La finestra corrisponde alla conservazione prevista dal piano: 30 giorni per Agency, 7 per gli altri; non esistono eventi precedenti da richiedere, perché gli eventi inoltrati vengono rimossi.
Caselle di posta condivise (del team)
Una casella di posta condivisa è una casella del team, come support@ o sales@, che i membri aprono tramite il proprio account di posta normale, nella webmail e, quando l'accesso nativo è abilitato, come cartella IMAP delegata. Non esistono una password condivisa o un accesso separato. L'accesso è uniforme: ogni membro può leggere e un singolo flag can_send stabilisce se può rispondere usando l'indirizzo (true) o dispone del solo accesso in lettura (false). Non esistono ruoli per i membri.
GET /api/v1/mailboxes e GET /api/v1/mailboxes/{id} ora restituiscono mailbox_type ("user" o "shared") e il valore booleano is_shared; le caselle condivise includono anche shared_member_count. Usa questi campi per distinguere una casella del team da una normale prima di chiamare gli endpoint dei membri.
| Endpoint | Metodo | Ambito richiesto | Cosa fa |
|---|---|---|---|
/api/v1/mailboxes/{id}/members |
GET | mailboxes:read |
Elenca i membri di una casella condivisa (per ciascuno: member_mailbox_id, email, can_read, can_send) |
/api/v1/mailboxes/{id}/members |
POST | mailboxes:write |
Aggiunge un membro, corpo {member_mailbox_id, can_send?} (il valore predefinito di can_send è true) |
/api/v1/mailboxes/{id}/members/{member} |
PATCH | mailboxes:write |
Attiva o disattiva l'accesso di risposta di un membro, corpo {can_send} |
/api/v1/mailboxes/{id}/members/{member} |
DELETE | mailboxes:write |
Rimuove un membro (una casella condivisa ne mantiene sempre almeno uno) |
/api/v1/shared-mailboxes |
POST | mailboxes:create |
Crea una casella condivisa, corpo {domain_id, local_part, display_name, member_mailbox_ids[], storage_shared?, storage_mb?} |
/api/v1/mailboxes/{id}/convert-to-shared |
POST | mailboxes:write |
Converte una casella esistente in una condivisa, corpo {member_mailbox_ids[]} (ruota la vecchia password impedendo nuovi accessi; restituisce 202 conversion_pending con un nuovo tentativo automatico se la sincronizzazione del backend non è ancora confermata) |
/api/v1/mailboxes/{id}/convert-to-regular |
POST | mailboxes:write |
Riconverte una casella condivisa in una normale, corpo {password} (rimuove i membri e imposta una nuova password di accesso) |
Gli endpoint dei membri riutilizzano gli ambiti esistenti mailboxes:read / mailboxes:write. Non esiste un ambito separato per le caselle condivise.
Per individuare l'accesso nativo dalle applicazioni di posta, chiama GET /api/v1/mailboxes/{member_mailbox_id}/client-setup per una casella regolare appartenente a un membro. Il relativo oggetto shared_mailboxes segnala la disponibilità nativa persistente, la disponibilità effettiva di Send As e il relativo motivo, i percorsi esatti di Inbox/Sent/Archive/Junk e le operazioni consentite. can_send è il permesso Can reply assegnato, non la prova che SMTP sia attualmente pronto. L'endpoint non restituisce mai una password. Chiamarlo con l'ID della casella condivisa restituisce 422 direct_login_unavailable, perché l'indirizzo condiviso non può autenticarsi direttamente.
La rimozione di un membro, la modifica di can_send o la conversione di una casella condivisa in normale sincronizza i permessi del server di posta quando l'accesso nativo è abilitato. Una risposta 503 native_access_sync_failed può essere ritentata e garantisce che l'associazione, il permesso o il tipo di casella siano rimasti invariati, anziché applicare l'operazione solo in parte.
Endpoint disponibili
Drive ha una propria documentazione di riferimento e non viene ripetuto qui; consulta la Panoramica della API Drive. Gli endpoint SMTP a livello di account mantenuti per compatibilità con le versioni precedenti sono descritti in Instradamento SMTP per dominio, anziché essere elencati come attuali.
| Endpoint | Metodo | Ambito richiesto |
|---|---|---|
/api/v1/domains |
GET | domains:read |
/api/v1/domains/{id} |
GET | domains:read |
/api/v1/domains/{id}/matching-addresses |
GET | domains:read |
/api/v1/domains/{id}/matching-addresses |
PUT | domains:write |
/api/v1/domains/{id}/matching-addresses |
DELETE | domains:write |
/api/v1/domains/{id}/dns-requirements |
GET | domains:dns:read |
/api/v1/domains/{id}/dns-recheck |
POST | domains:dns:recheck |
/api/v1/domains/{id}/spam-metrics |
GET | domains:read |
/api/v1/domains/{id}/spam-metrics/summary |
GET | domains:read |
/api/v1/domains/{id}/deliverability |
GET | domains:read |
/api/v1/domains/{id}/bounces |
GET | domains:read |
/api/v1/domains/{id}/signature |
GET | domains:read |
/api/v1/domains/{id}/forwarding-addresses |
GET | domains:read |
/api/v1/domains/{id}/forwarding-addresses/{addressId}/log |
GET | domains:read |
/api/v1/dns-checks/{id} |
GET | domains:dns:read |
/api/v1/mailboxes |
GET | mailboxes:read |
/api/v1/mailboxes |
POST | mailboxes:create |
/api/v1/mailboxes/{id} |
PATCH | mailboxes:write |
/api/v1/mailboxes/invites |
POST | mailboxes:invites:create |
/api/v1/mailboxes/invites:bulk |
POST | mailboxes:invites:create |
/api/v1/mailboxes:bulk |
POST | mailboxes:create |
/api/v1/mailboxes/{id}/forwarding |
GET | mailboxes:forwarding:read |
/api/v1/mailboxes/{id}/forwarding |
PUT | mailboxes:forwarding:write |
/api/v1/mailboxes/{id}/rules |
GET | mailboxes:rules:read |
/api/v1/mailboxes/{id}/rules |
POST | mailboxes:rules:write |
/api/v1/mailboxes/{id}/rules/{ruleId} |
GET | mailboxes:rules:read |
/api/v1/mailboxes/{id}/rules/{ruleId} |
PUT | mailboxes:rules:write |
/api/v1/mailboxes/{id}/rules/{ruleId} |
DELETE | mailboxes:rules:write |
/api/v1/mailboxes/{id}/rules/reorder |
PATCH | mailboxes:rules:write |
/api/v1/mailboxes/{id}/auto-reply |
GET | mailboxes:auto-reply:read |
/api/v1/mailboxes/{id}/auto-reply |
PUT | mailboxes:auto-reply:write |
/api/v1/mailboxes/{id}/sieve |
GET | mailboxes:rules:read |
/api/v1/mailboxes/{id}/sieve |
PUT | mailboxes:rules:write |
/api/v1/mailboxes/{id}:delete-intent |
POST | mailboxes:delete |
/api/v1/delete-intents/{id}:confirm |
POST | mailboxes:delete |
/api/v1/me |
GET | (qualsiasi token operativo valido) |
/api/v1/mailboxes/{id}/message-tokens |
POST | mailboxes:message-tokens:manage |
/api/v1/mailboxes/{id}/message-tokens |
GET | mailboxes:message-tokens:manage |
/api/v1/message-tokens/{id} |
DELETE | mailboxes:message-tokens:manage |
/api/v1/messages |
GET | messages:read (token di messaggistica) |
/api/v1/messages/{uid} |
GET | messages:read (token di messaggistica) |
/api/v1/messages/{uid} |
PATCH | messages:write (token di messaggistica) |
/api/v1/messages/send |
POST | messages:send (token di messaggistica) |
/api/v1/messages/_ping |
GET | messages:read (token di messaggistica, diagnostica) |
/api/v1/messages/{uid}/attachments/{index} |
GET | messages:read (token di messaggistica) |
/api/v1/messages/{uid}/attachments |
GET | messages:read (token di messaggistica) |
/api/v1/messages/{uid}/raw |
GET | messages:read (token di messaggistica; restituisce raw_base64, encoding, content_type, size_bytes) |
/api/v1/messages/folders |
POST | messages:write (token di messaggistica) |
/api/v1/messages/folders/{path} |
PATCH | messages:write (token di messaggistica) |
/api/v1/messages/folders/{path} |
DELETE | messages:write (token di messaggistica) |
/api/v1/messages/{uid}:spam |
POST | messages:write (token di messaggistica) |
/api/v1/messages/{uid}:ham |
POST | messages:write (token di messaggistica) |
/api/v1/messages/bulk |
POST | messages:write (token di messaggistica) |
/api/v1/messages/folders:empty |
POST | messages:write (token di messaggistica) |
/api/v1/messages/drafts |
POST | messages:write (token di messaggistica); restituisce uid + uidvalidity |
/api/v1/messages/drafts/{uid} |
PUT | messages:write (token di messaggistica); richiede il valore uidvalidity della bozza |
/api/v1/messages/scheduled |
POST | messages:send (token di messaggistica) |
/api/v1/messages/scheduled |
GET | messages:read (token di messaggistica) |
/api/v1/messages/scheduled/{id} |
PATCH | messages:send (token di messaggistica) |
/api/v1/messages/scheduled/{id} |
DELETE | messages:send (token di messaggistica) |
/api/v1/messages/contacts |
GET | messages:read (token di messaggistica) |
/api/v1/messages/contacts |
POST | messages:write (token di messaggistica) |
/api/v1/messages/contacts/{id} |
PATCH | messages:write (token di messaggistica) |
/api/v1/messages/contacts/{id} |
DELETE | messages:write (token di messaggistica) |
/api/v1/messages/contacts/import |
POST | messages:write (token di messaggistica) |
/api/v1/messages/contacts/export |
GET | messages:read (token di messaggistica) |
/api/v1/messages/contact-groups |
GET | messages:read (token di messaggistica) |
/api/v1/messages/contact-groups/{id}/members |
GET | messages:read (token di messaggistica) |
/api/v1/messages/external-accounts |
GET | messages:read (token di messaggistica) |
/api/v1/messages/external-accounts |
POST | messages:write (token di messaggistica) |
/api/v1/messages/external-accounts/{id} |
PATCH | messages:write (token di messaggistica) |
/api/v1/messages/external-accounts/{id} |
DELETE | messages:write (token di messaggistica) |
/api/v1/messages/external-accounts/detect |
POST | messages:read (token di messaggistica) |
/api/v1/messages/external-accounts/test |
POST | messages:write (token di messaggistica) |
/api/v1/messages/external-accounts/{id}/test |
POST | messages:write (token di messaggistica) |
/api/v1/messages/_me |
GET | qualsiasi token di messaggistica (introspezione) |
/api/v1/messages/calendar/events |
GET | messages:read (token di messaggistica) |
/api/v1/messages/calendar/events |
POST | messages:write (token di messaggistica) |
/api/v1/messages/calendar/events/{id} |
PATCH | messages:write (token di messaggistica) |
/api/v1/messages/calendar/events/{id} |
DELETE | messages:write (token di messaggistica) |
/api/v1/messages/{uid}/reply |
GET | messages:read (token di messaggistica) |
/api/v1/messages/{uid}/reply-all |
GET | messages:read (token di messaggistica) |
/api/v1/messages/{uid}/forward |
GET | messages:read (token di messaggistica) |
/api/v1/messages/contact-groups |
POST | messages:write (token di messaggistica) |
/api/v1/messages/contact-groups/{id} |
PATCH | messages:write (token di messaggistica) |
/api/v1/messages/contact-groups/{id} |
DELETE | messages:write (token di messaggistica) |
/api/v1/messages/contact-groups/{id}/members |
POST | messages:write (token di messaggistica) |
/api/v1/messages/contact-groups/{id}/members |
DELETE | messages:write (token di messaggistica) |
/api/v1/messages/identities |
GET | messages:read (token di messaggistica) |
/api/v1/messages/identities |
POST | messages:write (token di messaggistica) |
/api/v1/messages/identities/reply-policy |
PATCH | messages:write (token di messaggistica) |
/api/v1/messages/identities/{id} |
PATCH | messages:write (token di messaggistica) |
/api/v1/messages/identities/{id} |
DELETE | messages:write (token di messaggistica) |
/api/v1/messages/templates |
GET | messages:read (token di messaggistica) |
/api/v1/messages/templates |
POST | messages:write (token di messaggistica) |
/api/v1/messages/templates/{id} |
PATCH | messages:write (token di messaggistica) |
/api/v1/messages/templates/{id} |
DELETE | messages:write (token di messaggistica) |
/api/v1/messages/blocked-senders |
GET | messages:read (token di messaggistica) |
/api/v1/messages/blocked-senders |
POST | messages:write (token di messaggistica) |
/api/v1/messages/blocked-senders/{id} |
DELETE | messages:write (token di messaggistica) |
/api/v1/mailboxes/{id}/enable-imap |
POST | mailboxes:write (token operativo) |
/api/v1/migrations/test-connection |
POST | migrations:write |
/api/v1/migrations |
GET | migrations:read |
/api/v1/migrations/{id} |
GET | migrations:read |
/api/v1/migrations |
POST | migrations:write |
/api/v1/migrations/{id}:cancel |
POST | migrations:write |
/api/v1/migrations/{id}:retry |
POST | migrations:write |
/api/v1/migrations/{id} |
DELETE | migrations:write |
/api/v1/migrations/bulk/preview |
POST | migrations:write |
/api/v1/migrations/bulk |
POST | migrations:write |
/api/v1/migrations/bulk |
GET | migrations:read |
/api/v1/migrations/bulk/{batch} |
GET | migrations:read |
/api/v1/migrations/bulk/{batch}:cancel |
POST | migrations:write |
/api/v1/migrations/bulk/{batch}:retry |
POST | migrations:write |
/api/v1/migrations/bulk/{batch}:resume |
POST | migrations:write |
/api/v1/migrations/bulk/{batch} |
DELETE | migrations:write |
/api/v1/migrations/bulk/{batch}/jobs/{job}/password |
PATCH | migrations:write |
/api/v1/account |
GET | account:read |
/api/v1/billing/status |
GET | billing:read |
/api/v1/billing/invoices |
GET | billing:read |
/api/v1/domains |
POST | domains:create |
/api/v1/domains/{id} |
DELETE | domains:delete |
/api/v1/domains/{id}/catch-all |
PATCH | domains:write |
/api/v1/domains/{id}/mail-hosting |
PATCH | domains:write |
/api/v1/domains/{id}/forwarding-addresses |
POST | domains:write |
/api/v1/domains/{id}/forwarding-addresses/{addressId} |
PATCH | domains:write |
/api/v1/domains/{id}/forwarding-addresses/{addressId} |
DELETE | domains:write |
/api/v1/domains/{id}/dkim:retry |
POST | domains:write |
/api/v1/domains/{id}/note |
PATCH | domains:write |
/api/v1/domains/{id}/signature |
PATCH | domains:write |
/api/v1/domains/{id}/branding |
GET | domains:read |
/api/v1/domains/{id}/branding |
PATCH | domains:write |
/api/v1/domains/{id}/branding/logo/{slot} |
PUT | domains:write |
/api/v1/domains/{id}/branding/logo/{slot} |
DELETE | domains:write |
/api/v1/domains/{id}/branding/verify-dns |
POST | domains:write |
/api/v1/domains/{id}/branding/preview |
POST | domains:write |
/api/v1/domains/{id}/branding |
DELETE | domains:write |
/api/v1/domains:bulk-add |
POST | domains:create |
/api/v1/mailboxes/{id} |
GET | mailboxes:read |
/api/v1/mailboxes/{id}/client-setup |
GET | mailboxes:read |
/api/v1/mailboxes/{id}/apple-mail-profile |
GET | mailboxes:read |
/api/v1/mailboxes/{id}/bounces |
GET | mailboxes:read |
/api/v1/mailboxes/{id}/password |
POST | mailboxes:write |
/api/v1/mailboxes/{id}/note |
PATCH | mailboxes:write |
/api/v1/mailboxes/{id}:pause |
POST | mailboxes:write |
/api/v1/mailboxes/{id}:restore |
POST | mailboxes:delete |
/api/v1/mailboxes/{id}:resume |
POST | mailboxes:write |
/api/v1/mailboxes/{id}:suspend-login |
POST | mailboxes:write |
/api/v1/mailboxes/{id}:resume-login |
POST | mailboxes:write |
/api/v1/mailboxes:login-access |
POST | mailboxes:write |
/api/v1/mailboxes:drive-access |
POST | mailboxes:write |
/api/v1/mailboxes/{id}/members |
GET | mailboxes:read |
/api/v1/mailboxes/{id}/members |
POST | mailboxes:write |
/api/v1/mailboxes/{id}/members/{member} |
PATCH | mailboxes:write |
/api/v1/mailboxes/{id}/members/{member} |
DELETE | mailboxes:write |
/api/v1/shared-mailboxes |
POST | mailboxes:create |
/api/v1/mailboxes/{id}/convert-to-shared |
POST | mailboxes:write |
/api/v1/mailboxes/{id}/convert-to-regular |
POST | mailboxes:write |
/api/v1/tickets |
GET | tickets:read |
/api/v1/tickets/{id} |
GET | tickets:read |
/api/v1/tickets/{id}/messages |
GET | tickets:read |
/api/v1/tickets |
POST | tickets:write |
/api/v1/tickets/{id}:mark-seen |
POST | tickets:write |
/api/v1/tickets/{id}/reply |
POST | tickets:write |
/api/v1/tickets/{id}:close |
POST | tickets:write |
/api/v1/domains/{id}/smtp |
GET | smtp:read |
/api/v1/domains/{id}/smtp |
PUT | smtp:write |
/api/v1/domains/{id}/smtp/profiles |
GET | smtp:read |
/api/v1/domains/{id}/smtp/profiles |
POST | smtp:write |
/api/v1/domains/{id}/smtp/profiles/{connectionId} |
PUT | smtp:write |
/api/v1/domains/{id}/smtp/profiles/{connectionId} |
DELETE | smtp:write |
/api/v1/domains/{id}/smtp:test |
POST | smtp:write |
/api/v1/domains/{id}/smtp:test-status/{jobId} |
GET | smtp:read |
/api/v1/smtp/default |
GET | smtp:read |
/api/v1/smtp/default |
PUT | smtp:write |
/api/v1/smtp (legacy, compatibilità precedente) |
GET | smtp:read |
/api/v1/smtp (legacy, compatibilità precedente) |
PUT | smtp:write |
/api/v1/smtp/{id} (legacy, compatibilità precedente) |
DELETE | smtp:write |
/api/v1/smtp:test (legacy, compatibilità precedente) |
POST | smtp:write |
/api/v1/smtp:test-status/{jobId} (legacy, compatibilità precedente) |
GET | smtp:read |
/api/v1/messages/{uid} |
DELETE | messages:write (token di messaggistica) |
/api/v1/messages/{uid}:move |
POST | messages:write (token di messaggistica) |
/api/v1/messages/folders |
GET | messages:read (token di messaggistica) |
/api/v1/mailboxes/{id}/aliases |
GET | mailboxes:read |
/api/v1/mailboxes/{id}/aliases |
POST | mailboxes:write |
/api/v1/mailboxes/{id}/aliases/{aliasId} |
PATCH | mailboxes:write |
/api/v1/mailboxes/{id}/aliases/{aliasId} |
DELETE | mailboxes:write |
/api/v1/verify |
POST | verify:write |
/api/v1/verify/bulk |
POST | verify:write |
/api/v1/verify/bulk/{jobId} |
GET | verify:read |
/api/v1/verify/bulk/{jobId}/download |
GET | verify:read |
/api/v1/verify/credits |
GET | verify:read |
/api/v1/verify/bulk |
GET | verify:read |
/api/v1/verify/bulk/{jobId}/cancel |
POST | verify:write |
/api/v1/verify/bulk/{jobId} |
DELETE | verify:write |
/api/v1/cloudflare/validate-token |
POST | cloudflare:read |
/api/v1/cloudflare/zones |
POST | cloudflare:read |
/api/v1/cloudflare/connect |
POST | cloudflare:write |
/api/v1/cloudflare/preview |
POST | cloudflare:read |
/api/v1/cloudflare/apply |
POST | cloudflare:write |
/api/v1/cloudflare/tokens |
GET | cloudflare:read |
/api/v1/cloudflare/tokens/{id} |
DELETE | cloudflare:delete |
Gli endpoint Cloudflare seguono lo stesso flusso della dashboard: convalidare un token, elencare le zone, collegare i domini, visualizzare in anteprima le modifiche DNS e quindi applicarle. Sia /cloudflare/preview sia /cloudflare/apply accettano due controlli facoltativi per dominio:
included_records, un elenco consentito dei record da modificare, indicizzato per ID di dominio:{ "123": ["mx_primary", "spf_record"] }. I record esclusi vengono ignorati, quindi puoi applicare solo MX e SPF e tornare in seguito per DKIM. Ometti il campo per applicare tutti i record.confirmed_conflicts: quando l'anteprima segnala un record già esistente con un valore diverso, indica qui il relativo ID (con lo stesso formato{ domain_id: [record_ids] }) per autorizzarne la sostituzione.
Gli ID dei record (mx_primary, spf_record, dkim_primary, dmarc_main, …) provengono direttamente dalla risposta di anteprima. Un agente tipico richiama quindi prima l'anteprima e invia ad apply gli ID desiderati:
POST /api/v1/cloudflare/apply
{
"domain_ids": [123],
"included_records": { "123": ["mx_primary", "spf_record"] },
"confirmed_conflicts": { "123": ["dmarc_main"] }
}
Instradamento SMTP per dominio e impostazione predefinita dell'account
SMTP viene configurato per dominio. Ogni dominio sceglie una delle tre route: invio gestito dalla piattaforma, un profilo SMTP salvato (il tuo provider, riutilizzabile tra domini) oppure "non configurato". Un'unica impostazione predefinita per l'intero account determina la route iniziale dei nuovi domini.
Endpoint per dominio (smtp:read / smtp:write):
| Endpoint | Metodo | Cosa fa |
|---|---|---|
/api/v1/domains/{id}/smtp |
GET | Route corrente: smtp_mode, effective_smtp_mode, profile, effective_profile |
/api/v1/domains/{id}/smtp |
PUT | Imposta la route, corpo {smtp_mode: platform|profile|not_configured|inherit, smtp_connection_id?, set_account_default?, apply_to_all?} |
/api/v1/domains/{id}/smtp/profiles |
GET | Elenca i profili SMTP salvati dell'account |
/api/v1/domains/{id}/smtp/profiles/{connectionId}/usage |
GET | Elenca i domini e gli indirizzi Send As esatti che usano un profilo (senza credenziali) |
/api/v1/domains/{id}/smtp/profiles |
POST | Crea un profilo e lo usa per questo dominio |
/api/v1/domains/{id}/smtp/profiles/{connectionId} |
PUT | Aggiorna un profilo (influisce su ogni dominio che lo usa) |
/api/v1/domains/{id}/smtp/profiles/{connectionId} |
DELETE | Elimina un profilo (i domini che lo usano vengono riassegnati all'impostazione predefinita dell'account) |
/api/v1/domains/{id}/smtp:test |
POST | Verifica una route, restituisce {job_id, poll_url} |
/api/v1/domains/{id}/smtp:test-status/{jobId} |
GET | Controlla lo stato di un'attività di test |
Alcune note sul corpo della route:
smtp_mode=platformseleziona l'invio gestito;smtp_mode=profilerichiedesmtp_connection_id;not_configuredcancella la route.smtp_mode=inheritfa sì che il dominio segua in tempo reale l'impostazione predefinita dell'account: ogni volta che cambia il valore predefinito, cambia anche questo dominio. L'interfaccia web scrive sempre route concrete, ma il backend supporta ancorainherit; per questoGETrestituisceeffective_smtp_mode, che mostra il valore a cui corrisponde attualmenteinherit.set_account_default: trueè l'equivalente API dell'opzione Make this the account default della dashboard (i nuovi domini iniziano con questa route).apply_to_all: trueè il pulsante Apply to all domains (un passaggio unico di tutti i domini a questa route).
Endpoint per l'impostazione predefinita dell'intero account (smtp:read / smtp:write):
| Endpoint | Metodo | Cosa fa |
|---|---|---|
/api/v1/smtp/default |
GET | Restituisce default_smtp_mode (null finché non ne imposti uno), effective_default_smtp_mode (la base del piano usata quando non è impostato), default_smtp_connection_id e profile |
/api/v1/smtp/default |
PUT | Imposta il valore predefinito, corpo {smtp_mode: platform|profile|not_configured, smtp_connection_id?, apply_to_all?} |
Se elimini un profilo che era l'impostazione predefinita dell'account, questa viene ripristinata alla base del piano.
Endpoint legacy. Gli endpoint GET/PUT /api/v1/smtp a livello di account (e DELETE /api/v1/smtp/{id}, POST /api/v1/smtp:test, GET /api/v1/smtp:test-status/{jobId}) restano disponibili per la compatibilità con le versioni precedenti, ma non controllano più l'instradamento per dominio: usa gli endpoint per dominio e /smtp/default riportati sopra. Gli strumenti MCP legacy get_smtp_config / update_smtp_config sono deprecati per lo stesso motivo.
Branding White Label, clienti e accesso del team
Il branding viene configurato per dominio con branding:read / branding:write. Un dominio usa il proprio brand (mode=custom), eredita l'impostazione predefinita dell'account (mode=inherit) oppure è disattivato. È necessaria una prova White Label attiva o un componente aggiuntivo a pagamento. Dopo l'annullamento, il proprietario mantiene l'accesso di recupero in sola lettura durante il periodo di tolleranza mostrato. Leggi i dns_records del dominio e pubblica esattamente i record restituiti. Non ricavare nomi host o destinazioni CNAME da un esempio.
| Endpoint | Metodo | Cosa fa |
|---|---|---|
/api/v1/domains/{id}/branding |
GET | Legge il branding: mode, white_label_addon_active, brand, hosts, i dns_records da creare, cname_target e mail_zone |
/api/v1/domains/{id}/branding |
PATCH | Aggiornamento con unione parziale: mode, name, primary_color/accent_color, dashboard_enabled/dashboard_label, webmail_enabled/webmail_label, mail_zone_enabled, support_email, support_url, sender_email, scope |
/api/v1/domains/{id}/branding/logo/{slot} |
PUT | Carica un logo in base64 (slot = light|dark|favicon; PNG/JPG, ICO per favicon, ≤1 MB, nessun SVG). Il valore predefinito scope=domain richiede la modalità custom; un scope=account_default esplicito su un dominio inherit richiede un token senza vincoli. |
/api/v1/domains/{id}/branding/logo/{slot} |
DELETE | Rimuove uno slot del logo. Usa le stesse regole di ambito per dominio/impostazione predefinita dell'account; DELETE riceve scope come parametro di query. |
/api/v1/domains/{id}/branding/verify-dns |
POST | Accoda la verifica DNS per gli host brandizzati e la zona di posta del brand |
/api/v1/domains/{id}/branding/preview |
POST | Crea un URL di anteprima di breve durata (422 no_brand se il branding non è stato impostato) |
/api/v1/domains/{id}/branding?scope=domain|all |
DELETE | Cancella il branding per questo dominio o per l'intero account |
PATCH esegue un'unione parziale, quindi i campi omessi vengono mantenuti. Se il branding è attualmente disattivato, passa mode per riattivarlo. Un sender_email personalizzato deve appartenere a un dominio con una chiave DKIM verificata. mail_zone_enabled rende disponibili le applicazioni di posta e la sincronizzazione DAV sotto il dominio del brand. Appartiene al brand anziché a un singolo dominio, quindi richiede mode=custom o scope=account_default; un dominio inherit restituisce 422 inherited_brand. Leggi mail_zone.dns_status, mail_zone.client_hosts_status, mail_zone.records, mail_zone.dav_url e mail_zone.dav_ready per seguire il provisioning e usa solo un indirizzo DAV pronto. Per il flusso completo dell'agente, consulta la Guida alla API e a MCP per il branding White Label.
La superficie White Label a livello di account aggiunge 13 route in /api/v1/white-label: stato e avanzamento della configurazione, un catalogo degli accessi attivi, elenco dei membri e azioni del ciclo di vita, attività dell'account e cronologia delle azioni e degli accessi per membro. Usa members:read, members:write e activity:read. L'accesso è sempre l'intersezione tra i diritti dell'account, l'associazione corrente della persona, la concessione della credenziale e qualsiasi vincolo di dominio. Consulta Gestire team White Label con API e MCP per la tabella delle route e le transizioni di stato.
La specifica OpenAPI è disponibile in /api/openapi.json per l'importazione in Postman, Insomnia o nei generatori di codice.
Soluzioni rapide
- 401 "unauthenticated": verifica che l'header
Authorization: Bearer <token>sia presente e che il token non sia stato revocato o non sia scaduto. - 403 "plan_api_disabled": l'ambito richiesto non è incluso nel tuo piano. Nano include Email Verifier (e Drive, se hai acquistato il componente aggiuntivo Drive Storage). Passa a Starter o a un piano superiore per il resto della API.
- 403 "token_scope_blocked_by_plan": il token dispone di ambiti non disponibili nel piano corrente. Revoca il token e creane uno nuovo con gli ambiti consentiti.
- 403 "scope_blocked_by_entitlement": una concessione White Label memorizzata non è disponibile perché il componente aggiuntivo è inattivo o l'operazione è una scrittura durante il periodo di tolleranza. Riattiva White Label, quindi riemetti o autorizza nuovamente la credenziale.
- 403 "scope_blocked_by_membership": il ruolo corrente del membro è più ristretto dell'azione richiesta. Chiedi al proprietario di modificarlo; una nuova autorizzazione da sola non può ampliare l'associazione.
- 422 "missing_idempotency_key": aggiungi un header
Idempotency-Keyall'operazione di scrittura indicata nella documentazione dell'endpoint. - 403 "mailbox_sending_paused": l'invio da questa casella è stato interrotto perché la posta in uscita ha smesso di sembrare appartenere al proprietario, in genere a causa di una password finita nelle mani sbagliate. La lettura, gli elenchi e tutti gli altri endpoint continuano a funzionare; solo l'invio viene rifiutato e riprovare non rimuove il blocco. Devi cambiare la password della casella, dopodiché l'assistenza riattiverà l'invio. Consulta Perché non riesco a inviare email?.
- 429 limite di frequenza: attendi il periodo indicato nell'header
Retry-Afterprima di riprovare.
Invio di email: corpo, header e consegna
POST /api/v1/messages/send accetta la struttura di richiesta {to, subject, body: {text, html}, attachments, reply_to_message_id, headers}.
body.textebody.htmlsono entrambi facoltativi, ma almeno uno è obbligatorio. Se fornisci solobody.text, generiamo automaticamente un'alternativa HTML usando paragrafi<p>(le righe vuote separano i paragrafi; le singole interruzioni di riga diventano<br>), in modo che il messaggio venga visualizzato come una normale email in ogni client moderno. Se ti serve testo a spaziatura fissa, invia il valore letterale<pre>...</pre>inbody.html.headersè un oggetto facoltativo di header in uscita forniti dall'utente. L'elenco consentito comprendeList-Unsubscribe,List-Unsubscribe-Post,Reply-Toe qualsiasi header di tracciamento personalizzatoX-*. Gli altri nomi (From,Subject,Message-Id,Authentication-Resultse così via) sono gestiti dalla piattaforma e vengono rifiutati con422. Anche i valori che contengono CR/LF vengono rifiutati (protezione dall'iniezione di header). I valori sono limitati a 998 caratteri secondo RFC 2822.- Per i casi di invio in blocco o automazione, consulta la sezione Header di consegna per mittenti in blocco per configurare
List-Unsubscribee l'opzioneauto_list_unsubscribea livello di account.
Articoli correlati
Vai alle guide vicine che proseguono il flusso di lavoro.