Documentazione Mailzero

Elenca le deleghe permanenti

Le regole di delega permanente del proprietario in ordine: nome, il predicato di match, l'assegnatario (un'identità agent o un membro del workspace), il livello di autonomia, quante volte ciascuna ha fatto match. Richiede assistant:read; un token agent viene rifiutato.

Crea una delega permanente

Consegna un tipo di questione a un agent o a una persona una volta. match è un predicato esplicito, mai una chiamata al modello: uno qualsiasi tra senderAddress, senderDomain, organisation, workKeyPrefix, senderKind, mailboxIds, labels, subjectPattern (ancorato, case-insensitive), minOccurrences, minConfidence (la probabilità del classificatore calibrato su un'etichetta category:, da 0,5 a 1); ogni condizione dichiarata deve essere vera. Le regole sono ordinate e il primo match vince; il livello è observe salvo diversa indicazione. Una regola che fa match consegna il prossimo elemento corrispondente all'assegnatario, glielo comunica tramite la notifica di delega, e Today mostra perché. Richiede assistant:write; un token agent viene rifiutato.

Modifica una delega permanente

Rinomina, abilita o disabilita, riordina, cambia il match, l'assegnatario, il livello o le autorizzazioni. Abbassare il livello a observe è l'interruttore di emergenza con un clic di una regola. Richiede assistant:write; un token agent viene rifiutato.

Elimina una delega permanente

Rimuove la regola; gli elementi che ha consegnato tornano al proprietario, le ricevute di ciò che l'assegnatario ha fatto rimangono. Richiede assistant:write; un token agent viene rifiutato.

Prova le deleghe permanenti su fatti di esempio

Un'esecuzione di prova: quale regola prenderebbe un messaggio con questi fatti (mailbox, key, sender, subject, labels, occurrences), e perché. Nulla cambia. Richiede assistant:write; un token agente viene rifiutato.

Prova un effetto contro il livello e le autorizzazioni di una delega permanente

Una prova a secco dell'ordine di validazione per un effetto richiesto sotto la regola oggi: il livello consente il tipo; le autorizzazioni consentono i destinatari, il volume (conteggio degli effetti eseguiti oggi), la pianificazione, la spesa, le classi di rischio lette dalla pratica; l'approvatore richiesto ha approvato. Risponde con lo stato che un piano assumerebbe (proposed, approved, escalated o rejected) con ogni controllo e il motivo. Nulla cambia. Richiede assistant:write; un token agente viene rifiutato.

Leggi le metriche task

I sette numeri del livello task su una finestra mobile (trenta giorni per impostazione predefinita, window_days da 1 a 90), per l'account e per ogni delega permanente: matter chiusi senza il proprietario, il tempo dall'arrivo al completamento, i piani eseguiti come proposti, modificati e rifiutati, le escalation per matter, le correzioni dopo l'esecuzione, le collisioni, il costo del modello per matter. Letti dalle ricevute, dai piani, dalle escalation e dal registro; nulla è stimato. Richiede assistant:read.

Elenca la coda delle approvazioni

I piani in attesa del proprietario (proposti in bozza o trattenuti da una permissione) e le domande poste dagli assegnatari, tra le questioni che il lettore può vedere. Rispondi attraverso le interazioni dell'elemento di lavoro: approva o rifiuta un piano, scegli un'opzione o dai istruzioni su una domanda. Richiede assistant:read. Una questione creata dalla posta di autenticazione prima che questa venisse tenuta fuori dall'assistente viene mostrata con titolo, riepilogo, richiesta ed effetti del piano trattenuti per un lettore senza email:auth_secrets.

Elencare i suggerimenti di delega

Le deleghe permanenti proposte dall'assistente: una questione ricorsa almeno tre volte in novanta giorni (la stessa organizzazione o mittente) e gestita allo stesso modo ogni volta (ignored, answered, closed, handed to one agent), con la regola precompilata. Quelle aperte per impostazione predefinita. Nulla viene creato finché il proprietario non accetta. Richiede assistant:read; un token agente viene rifiutato.

Accettare o rifiutare un suggerimento di delega

Accettare: il suggerimento si chiude e la regola precompilata torna per essere creata dal client (POST /api/assistant/rules). Rifiutare: si chiude e non torna mai più per le stesse questioni e gestione. Richiede assistant:write; un token agente viene rifiutato.

Elenca le autorizzazioni associate agli assegnatari

Le autorizzazioni associate agli agenti e ai membri del proprietario, oltre a ogni regola che assegna loro pratiche; si applica il più restrittivo tra la regola e l'assegnatario. Richiede assistant:read; un token agente viene rifiutato.

Imposta le autorizzazioni di un assegnatario

Associa autorizzazioni a un'identità agente o a un membro dello spazio di lavoro; sostituiscono le autorizzazioni precedenti dell'assegnatario e limitano ogni regola che assegna loro pratiche. Richiede assistant:write; un token agente viene rifiutato.

Rimuovi le autorizzazioni di un assegnatario

L'assegnatario mantiene solo ciò che ogni regola concede. Richiede assistant:write; un token agente viene rifiutato.

Leggi una busta di task

La questione consegnata, come l'assegnatario ne ha bisogno: il riepilogo con le prove, i fatti, la delega (assegnatario, regola, livello, i tipi di effetto consentiti, le autorizzazioni effettive), i piani aperti e recenti, il lease. Un token agent legge le questioni consegnate ad esso e quelle delle caselle di posta che gestisce; il proprietario legge le proprie. Richiede assistant:read. Una questione creata dalla posta di autenticazione prima che questa venisse tenuta fuori dall'assistente viene mostrata con titolo, riepilogo, richiesta ed effetti del piano trattenuti per un lettore senza email:auth_secrets.

Prendi o rinnova il lease su un task

Due assegnatari non lavorano mai su una questione: il lease indica chi ci lavora fino a quando (quindici minuti per impostazione predefinita, fino a un'ora). Prenderlo di nuovo lo rinnova; un altro titolare viene rifiutato con TASK_LEASED fino alla scadenza. Una richiesta di effetti prende il lease autonomamente. Richiede assistant:write.

Restituisci il lease

Rilascia il lease detenuto dal chiamante; un lease detenuto da un altro assegnatario viene lasciato intatto. Richiede assistant:write.

Richiedi effetti su un task

L'assegnatario richiede uno o più effetti (reply, forward, label, snooze, resolve, note, request). Il livello della delega decide i tipi consentiti e le autorizzazioni li limitano: all'interno delle autorizzazioni a guarded_send o operate (e i tipi in entrata a triage) gli effetti vengono eseguiti immediatamente con le loro ricevute; a draft attendono l'approvazione del proprietario; un'autorizzazione fallita viene escalata al proprietario; un tipo che il livello non consente viene rifiutato. La richiesta del proprietario stesso viene eseguita immediatamente. La stessa chiave di idempotenza risponde di nuovo con il primo piano. Richiede assistant:write.

Fermarsi e chiedere al proprietario

L'assegnatario pone una domanda con l'evidenza e, quando utile, le opzioni che vede. Il proprietario risponde con le normali interazioni choose o instruct sulla decisione che questo crea; la questione appare in Today come necessitante il proprietario, il lease viene rilasciato, il task attende. Richiede assistant:write.

Rapporto su un task

Cosa ha fatto l'assegnatario e come è finito: done (la questione si risolve, o attende quando è ancora prevista una risposta), blocked (viene chiesto al proprietario), o handed back (il proprietario prende il controllo e la regola resta fuori da questa questione). I claim vengono riconciliati con le receipt che la piattaforma ha scritto: un claim senza receipt viene registrato come claim, mai come fatto. Il lease viene rilasciato. Richiede assistant:write.

Leggi ciò che l'assistente ha stabilito riguardo a un messaggio

La conoscenza che le analisi di questo messaggio hanno prodotto: affermazioni (soggetto, predicato, valore con tipo e valuta, base, confidenza, validità, evidenza), entità, impegni e aspettative. Nulla viene calcolato durante il processo: un messaggio che la pipeline non ha mai analizzato risponde analysed: false con reason (not_enabled quando la casella di posta non è nell'assistente, not_analysed quando l'analisi non è ancora avvenuta). Richiede assistant:read.

Estrai i campi di cui hai bisogno da un messaggio con il tuo schema

Una chiamata al modello sul testo del messaggio (oggetto, mittente, corpo) con uno schema JSON del chiamante di oggetti e primitive (fino a 8 KB, senza riferimenti): risponde data in quella forma, confidence (da 0 a 1) e evidence_quotes (estratti testuali). Memorizzato in cache da (messaggio, schema, istruzioni) quindi la stessa domanda costa una chiamata (cached: true dopo). Limitato dal budget del modello dell'account (429 quando esaurito, 503 quando il percorso del modello è disattivato). Le mail con codice di accesso rispondono 403 AUTH_MESSAGE. I corpi oltre 60.000 caratteri rispondono 413.

Ottieni impostazioni dell'assistente Mailzero

Restituisce lo stato di attivazione dell'assistente, i flag shadow/pause, la versione del consenso, il percorso privacy, l'ambito delle caselle di posta e tutte le caselle di posta che possiedi. Richiede l'autorizzazione assistant:read.

{
  "enabled": false,
  "shadow_enabled": true,
  "paused": false,
  "mailbox_ids": [
    "mbx_123"
  ],
  "history_window_days": 30,
  "privacy_route": "private_cloud",
  "attachment_vision": false,
  "pipeline_version": "communication-analysis.v1",
  "consent": {
    "required_version": "mailzero-personal-ai.v1",
    "accepted_version": "mailzero-personal-ai.v1",
    "accepted_at": "2026-09-02T09:12:00.000Z"
  },
  "mailboxes": [
    {
      "id": "mbx_123",
      "slug": "hello",
      "domain": "example.com",
      "name": "Hello",
      "kind": "api",
      "address": "hello@example.com"
    }
  ]
}

Aggiorna impostazioni dell'assistente Mailzero

Abilita, mette in pausa, riprende o delimita esplicitamente l'elaborazione dell'assistente. Inviare mailbox_ids: [] disabilita tutte le caselle di posta e annulla un'importazione cronologia in corso. La ripresa richiede la versione corrente del consenso. La ricezione della posta rimane indipendente. Richiede l'autorizzazione assistant:write.

{
  "ok": true,
  "enabled": true,
  "shadow_enabled": true,
  "paused": false,
  "mailbox_ids": [
    "mbx_123"
  ]
}

Acconsentire e avviare un'importazione cronologia in background

Registra il consenso esplicito IA corrente, abilita l'elaborazione in background sulle caselle di posta selezionate dell'utente e crea un'importazione riprendibile della cronologia recente. Il client può chiudersi immediatamente ed effettuare polling su GET /api/assistant/backfill. Richiede l'autorizzazione assistant:write.

{
  "ok": true,
  "preview": {
    "mailbox_ids": [
      "mbx_123"
    ],
    "history_window_days": 30,
    "scanned": 0,
    "enqueued": 0,
    "capped": false,
    "background": true,
    "backfill_id": "bf_456"
  }
}

Ottenere il progresso dell'importazione cronologia in background

Restituisce la fase di scansione/analisi, i messaggi elaborati e totali, la percentuale, l'ETA adattivo, lo stato di pausa e se l'app può chiudersi. Richiede l'autorizzazione assistant:read.

{
  "backfill": {
    "id": "bf_456",
    "status": "processing",
    "phase": "analysis",
    "paused": false,
    "processed": 12,
    "total": 40,
    "failed": 0,
    "percent": 30,
    "estimated_seconds_remaining": 240,
    "estimated_completion_at": "2026-09-02T09:20:00.000Z",
    "can_close_app": true,
    "started_at": "2026-09-02T09:12:00.000Z",
    "completed_at": null
  }
}

Ritentare i messaggi di importazione cronologia falliti

Rimette in coda i fallimenti terminali dall'importazione più recente per le caselle di posta che rimangono abilitate all'IA. I tentativi automatici sono già stati esauriti prima che un messaggio appaia qui. Richiede l'autorizzazione assistant:write.

{
  "ok": true,
  "retried": 2
}

Ottenere la coda delle decisioni fondate di Today

Restituisce le proiezioni versionate Now, Needs you, Waiting, Upcoming e Handled recenti con as_of, lag, coverage e warnings. Ogni elemento rimanda al messaggio di origine; nulla qui invia posta. Richiede l'autorizzazione assistant:read. La posta di autenticazione (codici di accesso, reimpostazioni della password, link magici) non diventa mai una questione e non raggiunge mai un modello. Una questione creata dalla posta di autenticazione prima che questa venisse tenuta fuori dall'assistente viene mostrata con titolo, riepilogo, richiesta ed effetti del piano trattenuti per un lettore senza email:auth_secrets.

{
  "type": "today",
  "as_of": "2026-09-02T09:15:00.000Z",
  "projection_lag_ms": 4200,
  "category": null,
  "categories": {
    "partner_inquiry": 1
  },
  "tag": null,
  "tags": {
    "lumenworks": 1
  },
  "sections": {
    "now": [
      {
        "id": "wi_789",
        "version": 3,
        "status": "needs_judgment",
        "title": "Investor update",
        "summary": "Paul needs the August metrics before his 16:00 partner call.",
        "category": "partner_inquiry",
        "tags": [
          "lumenworks"
        ],
        "proposed_tags": [],
        "mailbox": {
          "id": "mbx_123",
          "address": "hello@example.com",
          "name": "Hello"
        },
        "source": {
          "type": "domani-postgres",
          "conversation_id": "conv_1",
          "event_id": "msg_1",
          "revision": 1
        },
        "attention": {
          "level": "now",
          "reason": "Deadline today from a known investor",
          "confidence": "high",
          "deadline": "2026-09-02T16:00:00.000Z"
        },
        "decision": {
          "id": "dec_1",
          "version": 1,
          "status": "open",
          "question": "How do you want to answer Paul?",
          "options": [
            {
              "id": "opt_send",
              "label": "Send current metrics",
              "recommended": true
            },
            {
              "id": "opt_tomorrow",
              "label": "Ask for tomorrow"
            }
          ]
        }
      }
    ],
    "needs_you": [],
    "waiting": [],
    "upcoming": [],
    "handled": []
  }
}

Ottieni un elemento Work dell'assistente e il piano attuale esatto

Restituisce l'elemento Work fondato, la sua Decision aperta e le opzioni, il piano Action attuale esatto, impegni e aspettative aperti, interazioni e ricevute. Richiede l'autorizzazione assistant:read. Una questione creata dalla posta di autenticazione prima che questa venisse tenuta fuori dall'assistente viene mostrata con titolo, riepilogo, richiesta ed effetti del piano trattenuti per un lettore senza email:auth_secrets.

Leggi il riassunto della situazione di un elemento di lavoro

Un documento che un agente legge prima di agire: la situazione (stato, attenzione, ricorrenza, mittente), la storia finora (ogni mail di essa, analizzata o meno), i fatti che le analisi hanno stabilito (affermazioni con valore, base e validità, e le entità), gli impegni e le aspettative aperti con ciò che è atteso da chi e da quando, ciò che è già risolto (cicli chiusi e ricevute), la Decisione attuale con le sue opzioni, un prossimo passo suggerito (l'opzione raccomandata della Decisione quando ce n'è una, altrimenti una regola: una promessa scaduta, un'aspettativa scaduta da sollecitare, la richiesta del mittente a cui rispondere), e i messaggi di prova. Deterministico ed economico: nessuna chiamata al modello. I token agente leggono gli elementi delle caselle di posta che operano e gli elementi loro consegnati.

Leggi il riassunto della situazione per un corrispondente

Cosa sapere prima di rispondere a una persona: il riassunto del loro elemento di lavoro attivo più recente tra le caselle di posta che puoi leggere (o una casella di posta), gli altri elementi di cui sono responsabili, e le loro ultime dieci mail. brief è null quando non è stato ancora analizzato nulla da loro.

Leggi i fatti dietro un elemento Work

Le affermazioni e le entità unite da ogni analisi dell'elemento (la più recente vince), più i suoi impegni e aspettative memorizzati con il loro stato. I token degli agenti leggono gli elementi delle caselle di posta che operano e gli elementi a loro affidati.

Contrassegnare un elemento Work come aperto

Registra che il proprietario ha aperto questo elemento Work nella versione attuale, rimuovendo il contrassegno di non letto finché l'elemento non cambia di nuovo. Richiede l'ambito assistant:write.

Cosa ha imparato l'assistant su di te

Le regole di silenzio che l'assistente propone dopo che lo stesso mittente o la stessa organizzazione è stata ignorata a ogni ritorno, i silenzi in vigore (un mittente, un dominio o una situazione che l'assistente tiene fuori da Oggi), ognuno con il suo motivo, e le etichette confermate una volta, ognuna applicata alla prossima pratica dello stesso progetto senza domande. Accetta una regola di silenzio tramite l'endpoint suggestions; dimentica un silenzio con l'endpoint mutes, un'etichetta con l'endpoint tags.

Dimentica un mute

La prossima mail di quel mittente, dominio o situazione diventa di nuovo un item.

Dimentica un'etichetta

Niente viene più applicato senza domande: la prossima pratica di quel progetto propone di nuovo l'etichetta. Le pratiche che la portano la conservano.

Indagare una questione: cosa dicono il registro e i link

Legge, in quell'istante, i fatti che l'infrastruttura pubblica detiene sul dominio del mittente (la sua data di registrazione e registrar, la sua postura SPF e DMARC, se riceve posta), dove ogni link del messaggio sorgente va realmente (i redirect seguiti un hop alla volta, l'host finale e i fatti del suo dominio), e cosa ogni allegato è realmente (i suoi primi byte rispetto al nome e al tipo dichiarato). Risponde con il dossier con i segnali che i fatti aggiungono (un dominio registrato giorni fa, un link che atterra altrove, un dominio del mittente che non protegge nulla, un programma nominato come documento). Nessun vendor, nessun account, nulla memorizzato; una ricerca che fallisce è un fatto a sé.

Chi c'è dietro una pratica: l'organizzazione, le persone coinvolte, la cronologia

Risponde la scheda del mittente di una pratica: l'organizzazione del mittente come la conosce il profilo di dominio memorizzato (nome, ragione sociale, categoria, sito web, data di registrazione, postura di posta; null per un dominio di posta condiviso come gmail.com o un dominio mai analizzato, e mai un'analisi dal vivo), le persone che i messaggi della storia portano in from, to e cc con i loro ruoli e se appartengono alla stessa organizzazione (le caselle del lettore stesso escluse), e la relazione: quanta posta è arrivata da questo indirizzo nelle caselle del lettore (contata fino a 50), quando la prima e l'ultima volta, le altre pratiche del mittente e le pratiche sollevate da colleghi dello stesso dominio. Richiede lo scope assistant:read.

Registra una Decision umana delimitata

Scegli un'opzione, dai un'istruzione, prendi il controllo, posticipa, ignora, correggi, segnala il verdetto di fiducia (phishing o legittimo), oppure approva o rifiuta un piano in attesa (un piano approvato viene eseguito immediatamente, con le sue ricevute nella risposta). La chiamata è delimitata da work_item_version e ripetuta in modo idempotente da idempotency_key. Scegliere o istruire prepara una bozza esatta che passa comunque attraverso il normale flusso di risposta; questo endpoint non invia mai email. Richiede lo scope assistant:write.

Ottieni l'anteprima esatta dell'azione tramite ID opaco

Restituisce l'identità di risposta esatta, i destinatari, il corpo, gli impegni e gli effetti collaterali di un piano d'azione preparato, oltre alla sua scadenza e revisione di origine, in modo che un client possa mostrare cosa accadrà prima che l'utente invii tramite l'endpoint di risposta esistente con assistant_plan_id. Richiede lo scope assistant:read.

Ottieni l'attività dell'assistente con contenuto minimizzato

Elenca le interazioni e le ricevute recenti attribuite al chiamante senza i corpi dei messaggi. Richiede lo scope assistant:read.

Esporta i dati derivati dell'assistente

Esporta analisi, rivendicazioni accettate, decisioni, interazioni, ricevute e utilizzo del modello come allegato JSON. Non include mai i corpi delle email di origine o i byte degli allegati. Richiede lo scope assistant:write. Richiede anche email:auth_secrets (altrimenti 403 INSUFFICIENT_SCOPE): lo stato derivato può contenere ciò che l'assistente ha ricavato dalla posta di autenticazione prima che questa ne venisse esclusa.

Elimina dati derivati dall'assistente

Elimina in modo idempotente intelligence derivata, job, utilizzo del modello, dispositivi, importazioni e impostazioni preservando la posta sorgente. Richiede l'autorizzazione assistant:write.

{
  "ok": true,
  "deleted": {
    "work_items": 12,
    "claims": 40,
    "entities": 9,
    "jobs": 52
  },
  "source_mail_deleted": false
}

Registra un dispositivo per avvisi Now con dati riservati

Registra o ruota un token push crittografato per un'installazione app e ambiente. Solo l'app nativa chiama questo; richiede un assistente attivo e l'autorizzazione assistant:write.

Revoca una registrazione dispositivo

Revoca tutte le registrazioni push di un'installazione, ad esempio al logout. Richiede l'autorizzazione assistant:write.

Controlla lo stato del DNS della posta elettronica (MX, SPF, DMARC, DKIM)

Controlla la configurazione DNS della posta elettronica per un dominio: record MX, SPF, DMARC e DKIM. Rileva automaticamente il provider di posta elettronica dai record MX (Google Workspace, Proton, Fastmail).

{
  "domain": "mysite.com",
  "provider": "google-workspace",
  "mx": {
    "configured": true,
    "records": [
      "1 aspmx.l.google.com",
      "5 alt1.aspmx.l.google.com"
    ]
  },
  "spf": {
    "configured": true,
    "value": "v=spf1 include:_spf.google.com ~all"
  },
  "dmarc": {
    "configured": true,
    "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@mysite.com"
  },
  "dkim": {
    "configured": true,
    "selectors": [
      "google"
    ]
  }
}

curl https://domani.run/api/domains/mysite.com/email/check \
  -H "Authorization: Bearer domani_sk_xxx"

Ottieni lo stato di recapito della posta elettronica con ambito proprietario

Separa la disponibilità dell'autenticazione deterministica, i risultati di consegna ponderati per destinatario entro 30 giorni, lo stato di sicurezza dell'account e il posizionamento misurato del fornitore. Il punteggio di preparazione non è una probabilità della posta in arrivo e il posizionamento non misurato viene restituito come not_tested.

curl https://domani.run/api/domains/mysite.com/email/deliverability \
  -H "Authorization: Bearer domani_sk_xxx"

Configura la posta elettronica su un dominio

Preconfigurare il DNS e-mail su un dominio (facoltativo). Questo viene chiamato automaticamente da create_mailbox quando necessario. Passa force=true per sovrascrivere il provider di posta elettronica esistente (Google Workspace, Fastmail, Proton).

Rimuovere la posta elettronica da un dominio

Rimuovi la posta elettronica da un dominio, elimina tutte le caselle di posta e i messaggi e imposta emailEnabled su false. Modifica la posta dell'intero dominio, quindi un token confinato a caselle di posta riceve 403 MAILBOX_CONFINED.

Controlla lo stato DNS dell'e-mail

Controlla lo stato di verifica DNS dell'e-mail per un dominio. Restituisce se il dominio è verificato e pronto, i dettagli del record DNS e il conteggio delle cassette postali.

Crea una casella di posta su domani.run

Crea un indirizzo email gratuito su domani.run (es. hello@domani.run). Non è richiesta la proprietà del dominio. Limitato a 1 casella di posta @domani.run gratuita per utente. Molte lumache comuni sono riservate.

Elenca tutte le caselle di posta

Elenca tutte le cassette postali a cui può accedere l'entità agente in tutti i domini, incluse le autorizzazioni di aree di lavoro.

Crea una casella di posta

Creare un indirizzo email (casella di posta). Fornisci un indirizzo completo come "hello@mysite.com". Il DNS e-mail viene configurato automaticamente al primo utilizzo. Passa force=true per sovrascrivere un provider di posta elettronica esistente. La capacità della casella di posta del dominio personalizzato è determinata dall'account attivo o dal piano dell'area di lavoro. Ogni account può creare una casella di posta @domani.run gratuita separatamente con POST /api/email. Passa workspace_id per creare la casella di posta all'interno di uno spazio di lavoro di tua proprietà. Per un dominio personalizzato, adotta in modo esplicito e atomico il dominio e tutte le relative cassette postali di pari livello senza ambito in quell'area di lavoro; un dominio non può mai essere suddiviso tra aree di lavoro. Passa kind="hosted" per creare una vera casella di posta IMAP/SMTP sul tuo dominio (connetti Apple Mail, Thunderbird o qualsiasi client) invece della casella di posta API predefinita (invia/ricevi tramite API + webhook). Le cassette postali ospitate restituiscono i record DNS da pubblicare, le impostazioni del client di posta e una password dell'app monouso. Richiede un dominio di tua proprietà.

Elenca tutte le caselle di posta

Elencare tutte le cassette postali a cui può accedere l'entità agente, comprese le autorizzazioni di spazi di lavoro. Uguale a GET /api/email.

Ottieni i dettagli della casella di posta

Ottieni i dettagli di una casella di posta specifica tramite il suo indirizzo email completo (codificato URL, ad esempio ciao%40miosito.com).

Aggiorna casella di posta

Aggiorna il nome visualizzato, l'URL webhook o l'indirizzo email di inoltro di una casella di posta utilizzando il suo indirizzo email completo. Impostare su null per disabilitare/cancellare.

Elimina una casella di posta

Elimina una casella di posta tramite il suo indirizzo email completo. Richiede confirm=true nel corpo. Senza conferma, restituisce un'anteprima con message_count.

Invia un'e-mail

Invia un’e-mail da una casella identificata dal suo indirizzo completo. Il server esegue prima una policy obbligatoria e versionata: nega i problemi oggettivi di sicurezza e restituisce come avvisi i problemi di reputazione e qualità dei contenuti. Per una risposta collaborativa in thread, passa il lease di composizione, il reply_version osservato e una chiave di idempotenza stabile; il server rifiuta atomicamente risposte obsolete o doppie subito prima dell’invio. Massimo 20 destinatari univoci per messaggio. Limite: 100 destinatari all’ora per casella.

Verifica preliminare di un'e-mail in uscita

Esegui la policy lato server con la versione esatta utilizzata dall'endpoint di invio senza inviare o consumare la quota di posta elettronica. I collegamenti di autenticazione HTTPS pubblici su domini di terze parti sono consentiti con un avviso di reputazione. Gli URL locali/privati, i collegamenti di autenticazione non HTTPS e gli allegati eseguibili vengono bloccati; i corpi superiori a 102 KB producono un avviso di ritaglio.

Elenca le email

Elenca le email in una cartella canonica o in una vista virtuale. L’impostazione predefinita è Posta in arrivo. La posizione della cartella è indipendente dalla direzione del messaggio e dal verdetto di spam. La posta di autenticazione (OTP/codici di verifica, reimpostazioni della password, link magici) è contrassegnata dal tag security: "auth". I token senza l’ambito email:auth_secrets vedono questi messaggi con oggetto e corpo OSCURATI (redacted: true); i metadati (mittente, data) rimangono visibili. I filtri subject, q e attachments corrispondono a ciò che il chiamante può leggere: senza l'ambito, un messaggio del genere corrisponde solo per oggetto e corpo oscurati, quindi una ricerca del codice che contiene non trova nulla.

Cerca email per significato e per parole

Cerca nelle caselle di posta che puoi leggere, o in una casella con mailbox. Ibrido per impostazione predefinita: l'embedding del messaggio (pgvector, cosine) e l'indice delle parole pesate sono fusi per rank reciproco con un piccolo boost di recency, in un'unica istruzione; why indica quale ramo ha trovato corrispondenza. Operatori Gmail in q: from: to: cc: subject: label: filename: mailbox: is:unread|read|starred|unstarred has:attachment in:inbox|archive|sent|spam|trash|anywhere after:2026/08/01 before: newer_than:7d older_than:2w (h/d/w/m/y), "a phrase", -word o -from: per escludere, a OR b. Una query fatta solo di operatori elenca i messaggi corrispondenti dal più recente (why: filter). Codici e link di accesso, spam e posta di sistema non sono mai indicizzati; le caselle elencate in search_opt_out_mailbox_ids dell'assistente sono cercate solo per parole. Un token legato a un'identità agent cerca solo nelle caselle che il suo agent gestisce. Richiede email:read. Senza email:auth_secrets, la posta di autenticazione in arrivo viene esclusa prima dell'ordinamento: nessuna parola, operatore o filtro la trova, quindi la ricerca di un codice di accesso non trova nulla.

curl "https://domani.run/api/emails/search?q=facture+tucows+ao%C3%BBt&limit=5" \
  -H "Authorization: Bearer domani_sk_xxx"

Inizia a connettere una inbox Gmail

Restituisce l'URL di consenso Google associato al tuo account e al limite di importazione. Aprilo in un browser; dopo il consenso l'inbox diventa una casella di posta connessa al suo indirizzo, la posta ricevuta dopo il limite viene importata (predefinito: le ultime 24 ore), e la nuova posta segue man mano che arriva. Mai l'intera inbox: amplia successivamente con POST /api/emails/{address}/import. Richiede email:write. Google OAuth deve essere configurato sul server.

Inizia a connettere una casella di posta Outlook

Restituisce l'URL di consenso Microsoft associato al tuo account e al limite di importazione. Aprilo in un browser; dopo il consenso la casella diventa una mailbox connessa al proprio indirizzo, la posta ricevuta dopo il limite viene importata (predefinito: le ultime 24 ore), e la nuova posta segue man mano che arriva. Mai l'intera casella: amplia successivamente con POST /api/emails/{address}/import. Richiede email:write. OAuth Microsoft deve essere configurato sul server.

Elenca i modi in cui una casella di posta può essere connessa

Una riga per provider (Gmail, Outlook, qualsiasi casella di posta tramite inoltro, un indirizzo ospitato qui): come inizia la connessione (una schermata di consenso, una regola di inoltro, un indirizzo creato), cosa può fare la connessione (leggere, o leggere e scrivere), se importa posta più vecchia, e se questo server è configurato per esso. Mostra un pulsante di connessione solo quando configured è true; reason indica la variabile mancante per l'operatore. Richiede email:read.

Connetti un inbox tramite inoltro

Crea una casella di posta connessa all'indirizzo proprio dell'inbox e risponde con un indirizzo di inoltro sul dominio di inoltro della piattaforma, con i passaggi per Gmail, Outlook e altri provider. Aggiungi una regola di inoltro al provider; ciò che arriva a quell'indirizzo viene estratto (mittente originale, data, oggetto) e memorizzato sotto la casella di posta connessa. Gmail chiede all'indirizzo di inoltro di confermare: il codice e il link appaiono sulla connessione. La prima mail che torna, o una prova (POST /api/emails/{address}/connector/verify), rende la connessione attiva. Solo la nuova posta arriva in questo modo; la posta più vecchia non può essere importata. Richiede email:write. Il dominio di inoltro deve essere configurato sul server.

Invia una prova attraverso la regola di inoltro

Invia una mail all'inbox connesso; quando la regola di inoltro la riporta all'indirizzo di inoltro, la connessione diventa attiva. Solo per una connessione tramite inoltro. Richiede email:write.

Leggi la connessione di una casella di posta connessa

Tipo, stato, il limite di importazione, la fase di sincronizzazione (la scansione di importazione, poi cronologia), il progresso di importazione (scansionate, copiate, da analizzare, analizzate), l'ultima sincronizzazione e l'ultimo errore. Richiede email:read. La conferma di inoltro (il codice e il link di Gmail) è posta di autenticazione: senza email:auth_secrets il suo codice e il suo url sono null e riporta redacted: true. Un token confinato a caselle di posta trova solo le proprie caselle (altrimenti 404).

Disconnetti una casella di posta connessa

Rimuove le copie personali (messaggi, allegati, righe di ricerca, lavori in sospeso) e le credenziali; mantiene la riga della casella di posta, il collegamento contrassegnato come disconnesso e ciò che hanno fatto gliagente (ricevute). Solo una casella di posta connessa può essere disconnessa. Richiede email:write.

Importa posta più vecchia di una casella di posta connessa

Amplia l'importazione a una data precedente: una nuova esecuzione di importazione copia la posta tra il nuovo limite e quello corrente, in ordine di arrivo, sotto il proprio limite di costo. Rifiutato mentre una scansione di importazione è ancora in esecuzione. Richiede email:write.

Cerca in una casella per significato e per parole

La stessa ricerca di GET /api/emails/search, limitata a questa casella. Richiede email:read. Senza email:auth_secrets, la posta di autenticazione in arrivo viene esclusa prima dell'ordinamento: nessuna parola, operatore o filtro la trova, quindi la ricerca di un codice di accesso non trova nulla.

Elenca le conversazioni di una casella di posta

Messaggi raggruppati nel modo in cui i client di posta li raggruppano: una risposta si unisce al thread del messaggio a cui risponde (In-Reply-To, poi la catena References), la posta senza intestazioni utilizzabili si unisce al thread più recente con lo stesso oggetto e un corrispondente in comune entro trenta giorni, tutto il resto avvia un thread il cui id è l'id del suo primo messaggio. I thread sono ordinati per ultima attività; cestino e spam non partecipano mai a meno che non siano nominati come cartella. folder=inbox|archive|sent mantiene i thread che hanno un messaggio lì ma conta comunque l'intera conversazione.

Leggi una conversazione, messaggio più vecchio per primo

Ogni messaggio del thread (cestino incluso, quindi nulla manca dalla storia) con il suo testo, più vecchio per primo, più i partecipanti e il conteggio dei non letti. La posta di autenticazione è oscurata nel modo in cui lo sono le letture dei messaggi.

Trasmetti eventi della casella di posta (server-sent events)

Risponde con text/event-stream. Senza un cursor lo stream inizia dal presente; con since (un cursor da /api/email/changes o l'id di qualsiasi evento precedente) riproduce prima ogni modifica dopo quel punto, poi segue il journal della casella di posta in tempo reale: ogni frame porta il tipo della modifica come nome dell'evento (message.received, message.updated, message.deleted, message.moved, message.status, mailbox.resync_required, assistant.item.delegated, assistant.item.recalled, ...), la modifica come dati JSON con il suo cursor ripristinabile, e quello stesso cursor come id del frame. Il primo frame è ready con il cursor da cui riprendere; un commento keep-alive arriva ogni 20 secondi; la connessione si chiude dopo circa 5 minuti con un frame close e un suggerimento retry:. Riconnettiti con Last-Event-ID (o since) per riprendere senza interruzioni e senza duplicati. I token degli agente sono limitati alle caselle di posta su cui opera l'agente. Una voce su un elemento di lavoro creato dalla posta di autenticazione riporta title e ask oscurati per un token senza email:auth_secrets.

Elenca le cartelle e i conteggi della posta elettronica

Restituisce conteggi derivati dal server per cartelle di sistema e visualizzazioni virtuali, oltre a funzionalità del ciclo di vita per il backend della casella di posta.

Applicare un'azione del ciclo di vita ai messaggi

Sposta, ripristina, contrassegna come letti, contrassegna come Speciali o elimina definitivamente fino a 100 ID di messaggi espliciti. Lo spostamento nel Cestino è reversibile. L'eliminazione permanente richiede email:delete e accetta solo i messaggi già nel Cestino. Ogni risposta è una ricevuta di operazione durevole con un risultato per ID richiesto. Fornisci una chiave stabile nell'intestazione standard Idempotency-Key o nel campo JSON legacy idempotency_key e riutilizzala dopo i timeout; un tentativo esatto restituisce la ricevuta memorizzata senza un'altra mutazione. Se vengono forniti entrambi i moduli, devono corrispondere. Riutilizzare una chiave con una richiesta diversa restituisce 409. Se omesso, il server crea una chiave e la restituisce nel corpo e nell'intestazione Idempotency-Key. Restituisce 207 quando solo una parte del batch riesce.

Contrassegna i messaggi come letti o non letti

Endpoint di compatibilità per aggiornamenti dello stato di lettura a prova di tentativo. Restituisce la ricevuta canonica dell'operazione durevole per articolo più il conteggio legacy. Fornisci e riutilizza l'intestazione Idempotency-Key o il campo di compatibilità idempotency_key dopo i timeout.

Eliminazione collettiva dei messaggi

Endpoint di compatibilità che sposta in modo sicuro i messaggi nel Cestino. Restituisce la ricevuta canonica dell'operazione durevole per articolo più il conteggio legacy. Fornisci e riutilizza l'intestazione Idempotency-Key o il campo di compatibilità idempotency_key dopo i timeout.

Ricevi un messaggio

Recupera un singolo messaggio per ID da una casella di posta identificata dal suo indirizzo email completo. I messaggi classificati come posta di autenticazione (OTP, reimpostazione della password, collegamento magico) ritornano con l'oggetto/corpo oscurato a meno che il token non abbia l'ambito email:auth_secrets.

Elimina un messaggio

Sposta un messaggio nel Cestino. Questo è reversibile. Utilizza l'azione del ciclo di vita con delete_permanently e un token email:delete per cancellare un messaggio già nel Cestino.

Rispondi a un messaggio

Rispondi a un messaggio in una casella identificata dal suo indirizzo completo. Le intestazioni del thread vengono compilate automaticamente e l’originale viene citato sotto la risposta come fanno i client di posta (riga di attribuzione nella lingua dell’account, righe > nel testo, un blocco gmail_quote nell’HTML), a meno che quote sia false. I client collaborativi devono passare il lease di composizione, il reply_version osservato e una chiave di idempotenza stabile; il server rifiuta atomicamente una risposta obsoleta o doppia subito prima dell’invio.

Inoltra un messaggio

Inoltra un messaggio da una casella di posta identificata dal suo indirizzo email completo a un altro destinatario. L'inoltro della posta di autenticazione (OTP, reimpostazione della password, collegamento magico) richiede l'ambito email:auth_secrets: esfiltrerebbe il segreto.

Ottieni informazioni sull'avatar della casella di posta

Restituisce l'URL Gravatar (se impostato) e il collegamento di registrazione per una casella di posta identificata dal suo indirizzo email completo.

Ottieni la configurazione del webhook della casella di posta

Restituisce l'URL del webhook, il segreto di firma, i nomi delle intestazioni di autenticazione configurate e lo stato di una cassetta postale. I valori dell'intestazione non vengono mai restituiti.

Imposta il webhook della casella di posta

Configura la destinazione HTTPS per gli eventi della casella di posta firmati HMAC: la posta in entrata per impostazione predefinita, più (su adesione tramite events) il verdetto di consegna della posta inviata DALLA casella: un rimbalzo raggiunge il mittente pochi secondi dopo l'accettazione dell'invio, invece di vivere solo nella cronologia del messaggio. Le consegne in entrata in tempo reale vengono archiviate in modo duraturo, tentate immediatamente e ritentate fino a tre volte. Ogni tentativo include X-Domani-Delivery-Attempt a partire da 1. I valori facoltativi di autorizzazione o X-API-Key vengono crittografati e non vengono mai restituiti; gli operatori umani dovrebbero inviarli al di fuori del contesto del modello tramite le opzioni delle variabili di ambiente CLI.

curl -X PUT https://domani.run/api/emails/agent%40example.com/webhook \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://agent.example/webhook","events":["email.received","email.bounced","email.delivered"]}'

Rimuovere il webhook della casella di posta

Rimuovere l'URL del webhook e il segreto di firma da una casella di posta. Verranno archiviate solo le e-mail in entrata.

Ruota il segreto di firma del webhook

Rigenera il segreto di firma HMAC-SHA256 per un webhook della casella di posta. Il vecchio segreto viene immediatamente invalidato.

Testare il webhook della casella di posta

Invia un payload di prova firmato all'URL del webhook della casella di posta. Restituisce lo stato HTTP e se la consegna è riuscita. I test non vengono ripetuti; le consegne in entrata in tempo reale vengono ritentate fino a tre volte.

Elenca gli alias della casella di posta

Elenca tutti gli indirizzi alias recapitati in una casella di posta. Gli alias consentono a diversi indirizzi (vendite@, ciao@, contatto@) di condividere una casella di posta senza utilizzare uno slot della casella di posta.

Aggiungi un alias di casella di posta

Aggiungi un indirizzo alias che recapiti in questa casella senza occupare uno slot. L’alias deve appartenere allo stesso dominio della casella. Indica lo slug semplice ("sales") oppure l’indirizzo completo ("sales@mysite.com").

Rimuovere un alias di casella di posta

Rimuovere un alias da una casella di posta. L'e-mail a quell'indirizzo non verrà più recapitata.

Ottieni le impostazioni del client di posta (ospitato)

Ottieni le impostazioni di connessione IMAP/SMTP per una casella di posta ospitata, per configurare Apple Mail, Thunderbird o qualsiasi client di posta. Il nome utente è l'indirizzo completo; la password è una password dell'app (creane una con POST /api/emails/{address}/credentials). Solo caselle di posta ospitate.

Elenca le password delle app (ospitate)

Elenca le password dell'app per una casella di posta ospitata. I segreti vengono mostrati solo una volta al momento della creazione; questo restituisce solo etichette e metadati. Solo caselle di posta ospitate.

Creare una password per l'app (ospitata)

Crea una password dell'app per una casella di posta ospitata, utilizzata come password in un client di posta (IMAP/SMTP). Il segreto viene restituito una volta: archivialo ora. Solo caselle di posta ospitate.

Revoca la password di un'app (ospitata)

Revoca la password di un'app. Qualsiasi client di posta che lo utilizza interrompe immediatamente la connessione. Solo caselle di posta ospitate.

Segnala un messaggio a un umano

Escala un messaggio all’umano dell’account (oppure rimuovi la segnalazione con clear=true). Imposta needs_human sul messaggio, trattiene la sua conversazione nello stato needs_human e attiva il webhook email.escalated + una notifica in-app. La primitiva di prodotto dietro 'answer the easy ones, stop on the one the human must decide'.

Imposta un promemoria di follow-up

Imposta (o cancella con clear=true) un promemoria di follow-up una tantum su un messaggio. Quando arriva remind_at e il messaggio è ancora senza risposta (in entrata: nessuna risposta inviata; in uscita: nessuna risposta in entrata ricevuta), email.reminder_due si attiva come webhook + notifica in-app e il promemoria si cancella da solo.

Elenca i contatti

La rubrica dell’account, alimentata automaticamente dal traffico di posta: corrispondenti, conteggi dei messaggi, ultima attività e note. Per impostazione predefinita prima i più attivi di recente (order=recent), per la visualizzazione: un contatto che riceve nuova posta durante una scansione paginata passa davanti al cursore, quindi quella scansione può saltarlo. Per sincronizzare l’intera rubrica, passa order=created: prima i più vecchi per data di creazione e poi per id, una chiave che non cambia mai, quindi ogni contatto presente per tutta la scansione viene restituito esattamente una volta e i contatti creati nel frattempo arrivano alla fine. Un cursore prosegue solo l’ordine da cui proviene (altrimenti 400 INVALID_CURSOR). Aggrega i dati di tutte le caselle di posta, quindi i token confinati a una casella vengono rifiutati (400 MAILBOX_CONFINED).

Crea o aggiorna un contatto

Salva un contatto: imposta un nome visualizzato e allega delle note ('prefers short emails', 'decision maker at Acme'). Il traffico di posta continua comunque ad alimentare i conteggi dei messaggi.

Elimina un contatto

Rimuovi un contatto dalla rubrica. Il traffico di posta lo ricreerà come contatto automatico se dovesse scrivere di nuovo.

Elenca le regole della posta in entrata

Elenca le regole di filtraggio in entrata di una casella di posta, nell'ordine di priorità in cui vengono applicate (prevale la prima corrispondenza).

Aggiungi una regola per la posta in entrata

Aggiungi una regola eseguita sui messaggi in entrata che corrispondono a un campo (from/to/subject/body). Azioni: drop, mark_read, forward (action_arg = indirizzo), webhook_only (salta l’inoltro) e label (action_arg = etichetta). Le regole si applicano in ordine di priorità crescente; vince la prima corrispondenza.

Rimuovere una regola della posta in entrata

Rimuovere una regola di filtro in entrata da una casella di posta.

Imposta il dominio catch-all

Indirizza ogni email inviata a un indirizzo senza corrispondenza nel dominio in una casella di posta designata. Tutto ciò che non corrisponde a una casella di posta, a un sottoindirizzo o a un alias finisce nel catch-all. La casella di posta deve già esistere nel dominio. Modifica la posta dell'intero dominio, quindi un token confinato a caselle di posta riceve 403 MAILBOX_CONFINED.

Cancella dominio universale

Rimuovi il catch-all su un dominio. Le e-mail indirizzate a indirizzi non corrispondenti verranno nuovamente eliminate. Modifica la posta dell'intero dominio, quindi un token confinato a caselle di posta riceve 403 MAILBOX_CONFINED.

Sincronizza in modo incrementale una casella di posta

Chiama senza cursore per acquisire una linea di base prima di uno snapshot completo limitato. Quindi passa next_cursor per riprodurre le mutazioni avvenute durante e dopo quell'istantanea. I cursori sono opachi, firmati, associati alla casella di posta e scadono dopo 30 giorni. Le notifiche push sono solo suggerimenti di invalidazione; questo diario è la fonte di recupero durevole. Una voce su un elemento di lavoro creato dalla posta di autenticazione riporta title e ask oscurati per un token senza email:auth_secrets.

Elenca gli indirizzi soppressi

Elenca gli indirizzi nell'elenco di soppressione: mancati recapiti e reclami (acquisiti automaticamente dagli eventi di consegna) più inserimenti manuali. Gli invii a questi indirizzi vengono saltati. Impaginato con il cursore.

Aggiungi una soppressione

Aggiungi manualmente un indirizzo all'elenco di soppressione in modo che gli invii futuri lo saltino. I mancati recapiti permanenti e i reclami vengono aggiunti automaticamente; usalo per gli indirizzi a cui desideri interrompere l'invio di email. Idempotente.

Rimuovere una soppressione

Rimuovi un indirizzo dall'elenco di soppressione in modo da poterlo inviare nuovamente via email (ad esempio dopo che il destinatario ha corretto la propria casella di posta).

Richiedi un trasferimento della proprietà dell'area di lavoro

Solo proprietario. Invia un collegamento di accettazione di 48 ore a un membro esistente. Niente si muove finché il membro autenticato non accetta.

Revocare un trasferimento di proprietà in sospeso

Accetta la proprietà dell'area di lavoro

Solo target. Trasferisce atomicamente lo spazio di lavoro, i domini con ambito e le caselle di posta; il proprietario precedente diventa amministratore e il pagatore esistente rimane invariato.

Crea un nuovo account

Inizia la creazione di un nuovo account (o accede a uno esistente) inviando un link di accesso via e-mail; qui non viene restituita nessuna chiave API. Una persona che clicca su quel link da un browser arriva alla dashboard già autenticata. Una CLI o un agente senza sessione del browser dovrebbe usare invece il flusso di accesso da dispositivo (POST /api/auth/cli e poi interrogare GET /api/auth/cli/poll), che invia via e-mail la stessa approvazione e restituisce una chiave API una volta approvata - la risposta lo indica in next_steps. Passare un codice ref collega permanentemente il nuovo utente a un referente - il referente guadagna una commissione su tutti i futuri acquisti di domini di questo utente.

{
  "ok": true,
  "verification_required": true,
  "message": "Check your email for a sign-in link to finish creating your account.",
  "hint": "A human must open that email and click the link in a browser to finish verification; no API key is issued yet.",
  "next_steps": [
    "If a person can click the email link, nothing else to do: they land on the dashboard already signed in.",
    "If you are a CLI or agent without a browser session, start a device-login flow instead: POST /api/auth/cli, then poll GET /api/auth/cli/poll?code=... until status is \"complete\" - the same email approves it and hands back an API key, no browser needed on your side."
  ]
}

curl -X POST https://domani.run/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com"}'

Invia un'e-mail di accesso con collegamento magico

Invia un collegamento di accesso all'e-mail fornita. Se l'utente non esiste, crea prima un account. Il collegamento magico reindirizza alla dashboard con credenziali di autenticazione. Per l'accesso API programmatico, utilizza POST /api/auth/register per ottenere direttamente una chiave API.

{
  "ok": true,
  "message": "Check your email for a sign-in link."
}

curl -X POST https://domani.run/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com"}'

Verifica un token di collegamento magico

Convalida il token di collegamento magico e reindirizza al dashboard con credenziali di autenticazione. Utilizzato dall'e-mail di collegamento magico, in genere non chiamato direttamente dagli agenti. Gli agenti dovrebbero invece utilizzare POST /api/auth/register.

Genera un codice di accesso monouso tra host

Solo browser: consente a una persona che ha effettuato l’accesso su domani.run o mailzero.run di riprendere la sessione sull’altro host senza un secondo collegamento magico. Restituisce un URL il cui frammento contiene un codice monouso, valido 60 secondi e legato all’host; il codice non viene mai registrato nei log né inviato in una stringa di query. Non serve al di fuori di una sessione del browser, quindi non è esposto come strumento per agenti.

{
  "url": "https://mailzero.run/auth/handoff#code=xxx&next=%2Finbox"
}

Riscatta un codice di accesso monouso tra host

Solo browser: viene chiamato dalla pagina /auth/handoff sull’host di destinazione per scambiare il codice del frammento dell’URL con una sessione, esattamente come fa GET /api/auth/verify per un collegamento magico. Il codice deve corrispondere all’Host su cui è arrivata questa richiesta. Non è uno strumento per agenti.

{
  "ok": true,
  "next": "/inbox"
}

Ottieni i dettagli del conto corrente

Restituisce le informazioni sull'account dell'utente autenticato, inclusi e-mail, stato del pagamento, stato delle informazioni di contatto, codice di riferimento e conteggi di utilizzo. Gli agenti dovrebbero chiamarlo dopo l'autenticazione per verificare has_payment_method e has_contact prima di tentare gli acquisti.

{
  "id": "cm5abc123",
  "email": "dev@example.com",
  "plan": "agent",
  "workspace_plans": [
    "mail_pro"
  ],
  "has_payment_method": true,
  "has_contact": true,
  "referral_code": "x7k9m2",
  "referral_rate": 20,
  "domain_count": 3,
  "token_count": 2,
  "created_at": "2025-01-15T10:30:00.000Z"
}

curl https://domani.run/api/me \
  -H "Authorization: Bearer domani_sk_xxx"

Aggiorna le preferenze dell'account

Aggiorna il metodo di pagamento preferito dell'utente autenticato e/o la locale BCP 47. Le risposte API rimangono strutturate e non vengono tradotte.

Elimina account (bloccato mentre i domini sono trattenuti)

Elimina definitivamente l'account, i token, i webhook, le caselle di posta e gli altri dati dell'applicazione dell'utente autenticato. I domini registrati NON vengono eliminati con l'account: la richiesta fallisce con 409 HAS_DOMAINS finché tutti i domini non vengono trasferiti. Questa azione non può essere annullata.

Ottieni uno stato di attivazione veritiero e le azioni successive consigliate

Restituisce le tappe fondamentali del prodotto derivato dal server e le azioni successive basate sulle capacità. La creazione di token, l'utilizzo di token, le visualizzazioni di pagina e lo stato dell'elenco di controllo del client sono deliberatamente esclusi.

curl https://domani.run/api/me/activation \
  -H "Authorization: Bearer domani_sk_xxx"

Ignora o ripristina la guida di prima esecuzione

Memorizza solo la preferenza di presentazione. Non può completare un'attività cardine del prodotto.

Ottieni le informazioni di contatto del registrante

Restituisce le informazioni di contatto WHOIS del registrante per l'utente autenticato. Facoltative per gli acquisti (finché non sono impostate, il contatto di Domani detiene i nuovi domini per conto dell'utente), obbligatorie per un trasferimento in entrata.

{
  "has_contact": true,
  "contact": {
    "first_name": "Jane",
    "last_name": "Doe",
    "address1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US",
    "phone": "+1.2125551234",
    "email": "jane@example.com"
  }
}

curl https://domani.run/api/me/contact \
  -H "Authorization: Bearer domani_sk_xxx"

Imposta le informazioni di contatto del registrante

Imposta o aggiorna le tue informazioni di contatto WHOIS del registrante. Facoltative per gli acquisti, obbligatorie per un trasferimento in entrata. Diventano il contatto registrante e di fatturazione dei tuoi domini: finché non sono impostate, il contatto di Domani li detiene per tuo conto. A ogni aggiornamento, il nuovo contatto viene inviato a tutti i tuoi domini attivi presso i registrar che supportano le modifiche dei contatti, il che ti rende il loro registrante; il registrar può chiederti via email di confermarlo entro 15 giorni.

curl -X PUT https://domani.run/api/me/contact \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Jane","last_name":"Doe","address1":"123 Main St","city":"New York","state":"NY","postal_code":"10001","country":"US","phone":"+1.2125551234","email":"jane@example.com"}'

Invia nuovamente la verifica dell'e-mail di contatto

Invia nuovamente l’email di verifica all’indirizzo di contatto dell’account. Limitato a un invio ogni 15 minuti per indirizzo.

Elenca i dispositivi connessi

Ogni browser, app mobile e terminale con accesso all'account, prima la sessione di chi chiama (current). Ogni accesso apre una sessione propria, quindi accedere da un nuovo dispositivo non disconnette mai gli altri. La posizione è il luogo da cui il dispositivo ha effettuato l'accesso (paese e città dal suo IP), assente se sconosciuta. Le chiavi API non sono sessioni: elencale con GET /api/tokens.

{
  "sessions": [
    {
      "id": "cm5ses123",
      "current": true,
      "kind": "web",
      "product": "domani",
      "device": {
        "type": "desktop",
        "os": "macOS",
        "browser": "Chrome"
      },
      "location": {
        "country": "FR",
        "city": "Paris"
      },
      "signed_in_at": "2026-10-01T10:00:00.000Z",
      "last_active_at": "2026-10-18T09:12:00.000Z"
    },
    {
      "id": "cm5ses456",
      "current": false,
      "kind": "mobile",
      "product": null,
      "device": {
        "type": "mobile",
        "os": "iOS",
        "browser": null
      },
      "location": {
        "country": "FR",
        "city": "Lyon"
      },
      "signed_in_at": "2026-09-20T18:30:00.000Z",
      "last_active_at": "2026-10-17T21:04:00.000Z"
    }
  ],
  "hint": "Sign a device out with DELETE /api/sessions/{id}, or every device but this one with DELETE /api/sessions."
}

curl https://domani.run/api/sessions \
  -H "Authorization: Bearer domani_sk_xxx"

Disconnetti tutti gli altri dispositivi

Disconnette tutte le sessioni dell'account tranne quella che effettua la richiesta. A quei dispositivi verrà chiesto di accedere di nuovo alla prossima richiesta. Le chiavi API restano invariate.

{
  "revoked": 2,
  "hint": "Every other device is signed out. API keys are unchanged."
}

curl -X DELETE https://domani.run/api/sessions \
  -H "Authorization: Bearer domani_sk_xxx"

Disconnetti un dispositivo

Disconnette una sessione. current indica la sessione che effettua la richiesta (disconnettersi non richiede alcun ambito); qualsiasi altra sessione richiede tokens:write.

{
  "success": true,
  "current": false,
  "hint": "That device is signed out and will be asked to sign in again."
}

curl -X DELETE https://domani.run/api/sessions/cm5ses456 \
  -H "Authorization: Bearer domani_sk_xxx"

Elenca i token API di un'identità agente

I token associati a questa identità agente (chiavi mascherate, scope, confinamento mailbox, ultimo utilizzo). Un token associato ad un agente è la vista di quell'agente su ogni superficie assistant e mail.

Assegna ad un agente la propria chiave API in una sola chiamata

Crea un token associato a questa identità agente, confinato alle mailbox che l'agente gestisce, con gli scope minimi di cui un agente ha bisogno (assistant:read, assistant:write, email:read, email:write). Con quella chiave l'agente legge solo il proprio Today, le proprie mailbox e gli elementi che gli sono stati assegnati; nominare un altro agente risponde 403 e le route riservate al proprietario (settings, backfill, export) lo rifiutano. La chiave completa viene restituita solo in questa risposta. Richiede tokens:write. Un agente che non gestisce alcuna casella di posta non riceve ambiti di posta per impostazione predefinita, e richiederli risponde 400 AGENT_MAILBOXES_REQUIRED: una chiave senza caselle raggiungerebbe tutte le caselle di posta dell'account.

curl -X POST https://domani.run/api/agents/identity/dave/tokens \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Dave on the laptop"}'

Revoca un token API di un agente

Revoca un token associato a questa identità agente. Smette di funzionare immediatamente. Richiede tokens:write.

Elenca i tuoi token API

Restituisce tutti i token API per l'utente autenticato. Le chiavi sono mascherate per motivi di sicurezza (primi 12 + ultimi 4 caratteri visibili). Utilizzalo per controllare i token attivi.

{
  "tokens": [
    {
      "id": "cm5abc123",
      "name": "Default",
      "key": "domani_sk_a...wxyz",
      "lastUsed": "2025-02-18T10:30:00.000Z",
      "expiresAt": null,
      "expired": false,
      "scopes": [
        "*"
      ],
      "createdAt": "2025-01-15T10:30:00.000Z",
      "max_per_tx": null,
      "max_per_month": null,
      "spent_this_month": 0,
      "parent_token_id": null,
      "agent_identity": null
    },
    {
      "id": "cm5def456",
      "name": "CI/CD",
      "key": "domani_sk_b...vwxy",
      "lastUsed": null,
      "expiresAt": "2025-05-01T14:00:00.000Z",
      "expired": false,
      "scopes": [
        "domains:read",
        "domains:write"
      ],
      "createdAt": "2025-02-01T14:00:00.000Z"
    }
  ]
}

curl https://domani.run/api/tokens \
  -H "Authorization: Bearer domani_sk_xxx"

Crea un nuovo token API

Crea un nuovo token API. La chiave completa viene restituita solo in questa risposta: conservala in modo sicuro. Puoi creare più token per separare l'accesso per diverse applicazioni.

{
  "id": "cm5ghi789",
  "name": "CI/CD Pipeline",
  "key": "domani_sk_x1Y2z3A4b5C6d7E8f9G0hIjK",
  "expiresAt": "2025-03-20T10:30:00.000Z",
  "scopes": [
    "domains:read",
    "domains:write"
  ],
  "createdAt": "2025-02-18T10:30:00.000Z",
  "max_per_tx": 25,
  "max_per_month": 100,
  "mailbox_ids": [],
  "http_route_policy": null
}

curl -X POST https://domani.run/api/tokens \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Pipeline"}'

Revoca un token API

Revoca permanentemente un token API. Tutte le applicazioni che utilizzano questo token perderanno immediatamente l'accesso. Questa azione non può essere annullata.

{
  "success": true
}

curl -X DELETE https://domani.run/api/tokens/cm5abc123 \
  -H "Authorization: Bearer domani_sk_xxx"

Elenca gli eventi di controllo della sicurezza

Restituisce il registro di audit di sicurezza dell’account, dal più recente: ciclo di vita dei token (creazione, revoca, tentativi di escalation), rifiuti per limite di spesa e max_price, addebiti, richieste di pagamento ed eliminazioni di account bloccate. Usalo per monitorare l’attività dei token dei tuoi agenti.

{
  "events": [
    {
      "id": "evt1",
      "tokenId": "cm5abc123",
      "type": "purchase.charged",
      "targetType": "domain",
      "targetId": "mysite.com",
      "metadata": {
        "amountCents": 1450,
        "operation": "buy",
        "method": "card"
      },
      "createdAt": "2026-07-11T10:00:00.000Z"
    },
    {
      "id": "evt2",
      "tokenId": "cm5abc123",
      "type": "purchase.denied_cap",
      "targetType": "domain",
      "targetId": "expensive.ai",
      "metadata": {
        "amountCents": 8470
      },
      "createdAt": "2026-07-11T09:58:00.000Z"
    }
  ],
  "next_cursor": null,
  "hint": "Security-relevant events for this account."
}

curl "https://domani.run/api/audit?limit=50" \
  -H "Authorization: Bearer domani_sk_xxx"

Elenca webhook

Elenca tutti gli endpoint webhook configurati per il tuo account. Restituisce l'URL, gli eventi sottoscritti e lo stato attivo per ciascun webhook. I segreti non vengono mai restituiti dopo la creazione. Un token confinato a caselle di posta vede solo i webhook confinati alle proprie caselle.

{
  "webhooks": [
    {
      "id": "cm5wh001",
      "url": "https://example.com/webhooks/domani",
      "events": [
        "domain.purchased",
        "dns.updated"
      ],
      "active": true,
      "created_at": "2026-02-25T10:00:00.000Z"
    }
  ],
  "hint": "1 webhook(s)."
}

curl https://domani.run/api/webhooks \
  -H "Authorization: Bearer domani_sk_xxx"

Crea webhook

Registra un nuovo endpoint webhook HTTPS. I valori facoltativi di autorizzazione o X-API-Key vengono crittografati quando sono inattivi e inclusi in ogni consegna. Il segreto della firma viene restituito una sola volta. Massimo 5 webhook per account. Un webhook creato da un token confinato a caselle di posta è confinato alle stesse caselle: non riceve alcun evento di posta da altre caselle.

{
  "id": "cm5wh001",
  "url": "https://example.com/webhooks/domani",
  "events": [
    "domain.purchased",
    "dns.updated"
  ],
  "secret": "whsec_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "active": true,
  "created_at": "2026-02-25T10:00:00.000Z",
  "hint": "Webhook created. Save the secret - it won't be shown again. Use it to verify incoming payloads with HMAC-SHA256."
}

curl -X POST https://domani.run/api/webhooks \
  -H "Authorization: Bearer domani_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hook","events":["domain.purchased","dns.updated"],"headers":{"Authorization":"Bearer sender_key_xxx"}}'

Aggiorna webhook

Aggiorna l'URL di un webhook, gli eventi sottoscritti, lo stato attivo o le intestazioni di autenticazione crittografate. Invia solo i campi che desideri modificare. Un token confinato a caselle di posta raggiunge solo i webhook confinati alle proprie caselle (altrimenti 404).

Elimina webhook

Elimina un endpoint webhook. Tutte le consegne in sospeso verranno annullate. Questa operazione non può essere annullata. Un token confinato a caselle di posta raggiunge solo i webhook confinati alle proprie caselle (altrimenti 404).

Elenca le consegne dei webhook

Ottieni tentativi di consegna recenti per un webhook. Mostra il tipo di evento, lo stato HTTP, il numero di tentativi ed eventuali errori. Utile per il debug di consegne non riuscite. Un token confinato a caselle di posta raggiunge solo i webhook confinati alle proprie caselle (altrimenti 404).

{
  "deliveries": [
    {
      "id": "cm5del001",
      "replay_of_id": null,
      "event_type": "domain.purchased",
      "status": "delivered",
      "http_status": 200,
      "attempts": 1,
      "last_error": null,
      "created_at": "2026-02-25T10:05:00.000Z"
    }
  ],
  "hint": "1 delivery(ies) for this webhook."
}

Riprodurre una consegna di webhook

Clonare e riconsegnare immediatamente un evento webhook immutabile. Il payload dell'evento e l'ID evento rimangono identici; la firma HMAC riceve un nuovo timestamp. Una chiave di idempotenza richiesta garantisce che i nuovi tentativi del chiamante non vengano mai inviati due volte. Un token confinato a caselle di posta raggiunge solo i webhook confinati alle proprie caselle (altrimenti 404). Un'eccezione al payload identico: un oggetto copiato dalla posta di autenticazione viene inviato oscurato, perché l'URL del webhook può essere cambiato dal primo invio.

Elenca i tipi di eventi webhook

Elenca tutti i tipi di eventi webhook disponibili con le descrizioni. Nessuna autenticazione richiesta.

{
  "events": [
    {
      "type": "domain.purchased",
      "description": "A new domain was successfully registered"
    },
    {
      "type": "dns.updated",
      "description": "DNS records were changed for a domain"
    },
    {
      "type": "transfer.completed",
      "description": "A domain transfer completed successfully"
    }
  ]
}

curl https://domani.run/api/webhooks/events

Elenca notifiche

Elenca le notifiche in-app con paginazione basata sul cursore. Include eventi delle transazioni, aggiornamenti delle inserzioni e avvisi di sistema. Richiede l’ambito notifications:read. Una notifica scritta prima che gli oggetti delle email venissero oscurati in scrittura si legge con l'oggetto della posta di autenticazione oscurato, in body e data.subject, per un token senza email:auth_secrets.

Ottieni il conteggio delle notifiche non lette

Endpoint leggero per il polling del conteggio delle notifiche non lette. Richiede l'ambito notifications:read.

{
  "unread_count": 3
}

Contrassegna la notifica come letta

Contrassegna una singola notifica come letta. Richiede l'ambito notifications:read.

Contrassegna tutte le notifiche come lette

Contrassegna tutte le notifiche non lette come lette. Richiede l'ambito notifications:read.

Ottieni le preferenze di notifica

Restituisce le preferenze di notifica dell'utente per ogni categoria e canale (in_app, email). Le preferenze mancanti sono abilitate per impostazione predefinita. Richiede l'ambito notifications:read.

Aggiorna le preferenze di notifica

Aggiorna le preferenze di notifica per categorie e canali specifici. Richiede l'ambito notifications:read.