Guida alla API REST TrekMail per sviluppatori

Apri TrekMail in Claude, scegli Connect, accedi e autorizza l’accesso. Non devi creare un token API. Controlla i permessi o scollega l’app in Agenti IA e API, Token, App collegate.

Il tuo marchio White Label: usa l’indirizzo MCP del tuo pannello personalizzato e assegna al connettore il nome del marchio. Aggiungilo come custom connector; la pagina pubblica TrekMail usa l’accesso TrekMail e non sostituisce il collegamento del tuo marchio.

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.

Leggere le email con una sola chiave

Su Pro e Agency, scegli Leggi email quando crei una chiave API. Il permesso esplicito è mailboxes:messages:read; mailboxes:read mostra solo indirizzi e dati di configurazione. Tutte le caselle include quelle attuali e future; puoi invece limitare l’accesso a domini e caselle selezionati. Le chiavi esistenti non ricevono nuovi permessi automaticamente.

Usa la chiave dell’account con le rotte GET qui sotto. Invio, eliminazione e modifiche richiedono ancora credenziali e permessi separati per i messaggi. MCP ospitato accetta OAuth, non tm_live_ o tm_msg_. L’errore sul tipo di token indica all’agente la rotta o l’autorizzazione corretta.

GET /api/v1/mailboxes/{mailbox}/messages
GET /api/v1/mailboxes/{mailbox}/folders
GET /api/v1/mailboxes/{mailbox}/messages/{uid}
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/raw
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/attachments/{index}

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 Agenti AI e API, Registro di controllo.
• 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.
• Password per le app di posta: gestisci password separate per IMAP, SMTP, calendari e contatti e scegli quali password accettano le app di posta. Non sostituiscono i token Bearer dell’API o i token della Message API. Consulta Password per le app di posta via API e MCP.
• Utilizzo dello spazio delle caselle di posta: list_mailboxes e get_mailbox restituiscono used_mb, quota_mb, allocation_mb e is_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:

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/mcp come 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 Agenti AI e API, Token, Crea token e invialo come Authorization: Bearer …. Consulta Creare e gestire token API.
• Non conosci ancora la API? Fai clic su Avvia il tour nella parte superiore della pagina Agenti AI e 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 Agenti AI e API, sotto Riferimento rapido. 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. Gli invii di messaggi fanno eccezione quando la consegna non è riuscita (per un limite di invio, per esempio): la API non riproduce più il 202 precedente, quindi lo stesso messaggio si può inviare di nuovo più tardi con lo stesso contenuto. Se specifichi un tuo X-Request-Id, usane uno nuovo per questo tentativo: la API considera una ripetizione anche un invio dalla stessa casella con lo stesso X-Request-Id, quindi con quello vecchio riceveresti solo la consegna originale non riuscita e non verrebbe inviato nulla. Un nuovo tentativo per un invio ancora in attesa o già consegnato riceve sempre la risposta originale.

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.

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.

Le nuove caselle normali, comprese quelle create in blocco, tramite inviti o da agenti IA, seguono Impostazioni account > Nuove caselle > Le app di posta richiedono password per le app, attiva per impostazione predefinita. Modificarla non cambia le caselle esistenti. POST /api/v1/mailboxes permette di scegliere un client_auth_mode pari a app_password_only o password_or_app_password; se omesso, si applica l’impostazione dell’account. Le risorse di elenco e dettaglio delle caselle riportano client_auth_mode e app_passwords_count (password per le app attive). Le caselle condivise non hanno password per le app né una modalità di accesso propria.

I sei strumenti MCP per gestire le password per le app sono list_mailbox_app_passwords, create_mailbox_app_password, rotate_mailbox_app_password, revoke_mailbox_app_password, set_mailbox_client_auth_mode, update_account. update_account: Imposta new_mailbox_client_auth_mode per le caselle future; quelle esistenti mantengono la propria modalità. Richiede mailboxes:write, un token o connettore del proprietario senza restrizioni sulle risorse e TREKMAIL_ALLOW_DESTRUCTIVE=true in stdio self-hosted.

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.

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.

La sospensione revoca definitivamente tutte le password per le app. Ripristinare l’accesso non le ripristina. Anche quando un amministratore imposta una nuova password della casella dalla dashboard, tramite API o agente IA, tutte le password per le app vengono revocate, come durante il recupero della password, la conversione in casella condivisa e lo spostamento in Eliminati di recente. Ripristinare una casella eliminata non le riattiva.

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.active indica se queste regole stanno trasferendo posta in questo momento. È false con un piano inferiore a requires_plan ed è false mentre è impostato paused_until (l'account ha superato la frequenza oraria di invio; consulta Limiti di invio per piano). Una regola può essere is_active: true senza eseguire consegne, quindi leggi delivery, non solo is_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 condivisa ha una propria posta in arrivo del team. can_read è Leggi e can_send è Invia come. Per aprire le cartelle serve Leggi. Inviare dalla casella condivisa con Message API richiede entrambi. Non ci sono password condivise, accessi separati o ruoli di membro.

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.

La conversione in casella normale rimuove tutti i membri. Imposta una nuova password per la webmail, poi crea password per le app di posta nella scheda Sicurezza.

Le modifiche possono restituire 422 no_access_left se entrambi i permessi verrebbero disattivati, 422 send_only_disabled se la modifica richiesta al permesso Leggi non è disponibile, o 422 last_reader se l’ultima persona attiva che legge perderebbe accesso. Usa Rimuovi per togliere ogni accesso e assegna il permesso Leggi a un altro membro attivo prima di rimuovere l’ultimo lettore. Ognuno di questi errori restituisce anche shared_mailbox_id, member_id per un membro esistente e un hint che indica la richiesta con cui risolverlo.

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 Invia come e il relativo motivo, i percorsi esatti di Inbox/Sent/Archive/Junk e le operazioni consentite. can_send è il permesso Invia come 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.

shared_mailboxes.items[] include solo membri con il permesso Leggi quando l’accesso nativo alle cartelle è abilitato. delegated_send_addresses è un elenco separato di indirizzi del team disponibili nel campo Da con id, email e display_name; può essere vuoto. Non dà accesso alle cartelle né verifica che l’invio sia pronto. Questi indirizzi non sono identità della Message API. Usa i server restituiti, anche con White Label, invece di copiare un server della piattaforma.

La rimozione di un membro, la modifica di can_read / 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.

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):

Alcune note sul corpo della route:

• smtp_mode=platform seleziona l'invio gestito; smtp_mode=profile richiede smtp_connection_id; not_configured cancella la route.
• smtp_mode=inherit fa 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 ancora inherit; per questo GET restituisce effective_smtp_mode, che mostra il valore a cui corrisponde attualmente inherit.
• set_account_default: true è l'equivalente API dell'opzione Imposta come predefinito dell’account della dashboard (i nuovi domini iniziano con questa route). apply_to_all: true è il pulsante Applica a tutti i domini (un passaggio unico di tutti i domini a questa route).

Endpoint per l'impostazione predefinita dell'intero account (smtp:read / smtp:write):

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.

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-Key all'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-After prima di riprovare. Anche quando si raggiunge il limite giornaliero della API per casella di posta la risposta è rate_limited, ma con retryable impostato su false, dimension impostato su api_mailbox_daily e un orario in resets_at: riprovare prima non serve, quindi attendi fino a quell'orario.
• 429 "sending_limit_exceeded": una delle tue quote di invio è esaurita. dimension indica quale e resets_at quando si rinnova. Riprovare prima non può funzionare, per questo retryable è false. GET /api/v1/messages/sending-limits indica in remaining_today a quanti altri destinatari la casella può inviare oggi. Quando il limite più basso è il totale giornaliero dell'account, limit_today è null e lo è anche remaining_today finché quel totale non si esaurisce (poi vale 0); un token operativo legge il totale con GET /api/v1/sending-limits. Se dimension è recipients_per_message, dividi invece il messaggio in più messaggi piccoli. Consulta Limiti di invio per piano.

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.text e body.html sono entrambi facoltativi, ma almeno uno è obbligatorio. Se fornisci solo body.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> in body.html.
• headers è un oggetto facoltativo di header in uscita forniti dall'utente. L'elenco consentito comprende List-Unsubscribe, List-Unsubscribe-Post, Reply-To e qualsiasi header di tracciamento personalizzato X-*. Gli altri nomi (From, Subject, Message-Id, Authentication-Results e così via) sono gestiti dalla piattaforma e vengono rifiutati con 422. 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-Unsubscribe e l'opzione auto_list_unsubscribe a livello di account.

Una risposta 202 significa che il messaggio è stato accettato, non che è già stato inviato. Le quote di invio vengono verificate di nuovo quando il messaggio esce dalla coda, quindi controlla l'esito con GET /api/v1/messages/deliveries/{request_id}, usando il request_id della risposta 202. Può verificarlo qualsiasi token di messaggistica della stessa casella, non solo quello che ha inviato il messaggio; un request_id sconosciuto restituisce 404. Se un limite l'ha fermato, status è failed e failure indica il limite (dimension) e quando si rinnova (resets_at). Un messaggio il cui invio non è riuscito si può inviare di nuovo più tardi con lo stesso contenuto. Se specifichi un tuo X-Request-Id, usane uno nuovo, perché quello vecchio restituisce solo la consegna originale. Un messaggio programmato che raggiunge un limite al momento dell'invio viene trattenuto come limit_reached e conservato per 7 giorni: elenca questi messaggi con GET /api/v1/messages/scheduled?status=limit_reached, inviane uno più tardi assegnandogli un nuovo scheduled_for con PATCH /api/v1/messages/scheduled/{id} oppure eliminalo con DELETE.