Documentação do Mailzero

Listar as delegações permanentes

As regras de delegação permanente do proprietário em ordem: nome, o predicado de correspondência, o destinatário (uma identidade de agente ou um membro do workspace), o nível de autonomia, quantas vezes cada uma correspondeu. Requer assistant:read; um token de agente é recusado.

Criar uma delegação permanente

Entregar um tipo de assunto a um agente ou uma pessoa uma vez. match é um predicado explícito, nunca uma chamada de modelo: qualquer um de senderAddress, senderDomain, organisation, workKeyPrefix, senderKind, mailboxIds, labels, subjectPattern (ancorado, insensível a maiúsculas/minúsculas), minOccurrences, minConfidence (a probabilidade do classificador calibrado em uma etiqueta category:, de 0,5 a 1); todas as condições declaradas devem ser verdadeiras. As regras são ordenadas e a primeira correspondência vence; o nível é observe a menos que dito o contrário. Uma regra correspondente entrega o próximo item correspondente ao destinatário, notifica através do aviso de delegação, e o Today mostra o porquê. Requer assistant:write; um token de agente é recusado.

Alterar uma delegação permanente

Renomear, habilitar ou desabilitar, reordenar, alterar a correspondência, o destinatário, o nível ou as permissões. Reduzir o nível para observe é o interruptor de desativação de um clique de uma regra. Requer assistant:write; um token de agente é recusado.

Excluir uma delegação permanente

Remove a regra; os itens que ela entregou retornam ao proprietário, os recibos do que o destinatário fez permanecem. Requer assistant:write; um token de agente é recusado.

Testar as delegações permanentes em fatos de amostra

Uma simulação: qual regra pegaria uma mensagem com esses fatos (caixa de entrada, chave, remetente, assunto, etiquetas, ocorrências), e por quê. Nada muda. Requer assistant:write; um token de agente é recusado.

Testar um efeito contra o nível e as permissões de uma delegação permanente

Uma execução de teste da ordem de validação para um efeito solicitado sob a regra hoje: o nível permite o tipo; as permissões permitem os destinatários, o volume (contagem de efeitos executados hoje), o cronograma, o gasto, as classes de risco lidas do assunto; o aprovador obrigatório aprovou. Responde o status que um plano tomaria (proposed, approved, escalated ou rejected) com cada verificação e o motivo. Nada muda. Requer assistant:write; um token de agente é recusado.

Ler as métricas de tarefa

Os sete números da camada de tarefa em uma janela móvel (trinta dias por padrão, window_days de 1 a 90), para a conta e para cada delegação permanente: assuntos fechados sem o proprietário, o tempo da chegada até a conclusão, os planos executados conforme proposto, editados e rejeitados, as escalações por assunto, as correções após execução, as colisões, o custo do modelo por assunto. Lido dos recibos, dos planos, das escalações e do livro-razão; nada é estimado. Requer assistant:read.

Listar a fila de aprovações

Os planos aguardando o proprietário (propostos em rascunho ou retidos por uma permissão) e as perguntas que os responsáveis fizeram, entre os assuntos que o leitor pode ver. Responda através das interações do item de trabalho: aprovar ou rejeitar um plano, escolher uma opção ou instruir sobre uma pergunta. Requer assistant:read. Um assunto criado a partir de um e-mail de autenticação antes que esse e-mail fosse mantido fora do assistente é exibido com título, resumo, pedido e efeitos do plano retidos para um leitor sem email:auth_secrets.

Listar as sugestões de delegação

As delegações permanentes que o assistente propõe: um assunto que ocorreu pelo menos três vezes em noventa dias (a mesma organização ou remetente) e foi tratado da mesma forma todas as vezes (ignorado, respondido, fechado, entregue a um agente), com a regra pré-preenchida. Abertas por padrão. Nada é criado até que o proprietário aceite. Requer assistant:read; um token de agente é recusado.

Aceitar ou descartar uma sugestão de delegação

Aceitar: a sugestão fecha e a regra pré-preenchida retorna para o cliente criar (POST /api/assistant/rules). Descartar: ela fecha e nunca retorna para os mesmos assuntos e tratamento. Requer assistant:write; um token de agente é recusado.

Listar as permissões anexadas aos destinatários

As permissões anexadas aos agentes e membros do proprietário, além de cada regra que lhes entrega assuntos; o mais restritivo entre a regra e o destinatário se aplica. Requer assistant:read; um token de agente é recusado.

Definir as permissões de um destinatário

Anexar permissões a uma identidade de agente ou um membro do workspace; elas substituem as permissões anteriores do destinatário e limitam cada regra que lhes entrega assuntos. Requer assistant:write; um token de agente é recusado.

Remover as permissões de um destinatário

O destinatário mantém apenas o que cada regra concede. Requer assistant:write; um token de agente é recusado.

Ler um envelope de tarefa

O assunto transferido, conforme o destinatário precisa: o resumo com a evidência, os fatos, a delegação (destinatário, regra, nível, os tipos de efeito permitidos, as permissões efetivas), os planos abertos e recentes, o arrendamento. Um token de agent lê os assuntos transferidos a ele e aqueles das caixas de entrada que opera; o proprietário lê os seus próprios. Requer assistant:read. Um assunto criado a partir de um e-mail de autenticação antes que esse e-mail fosse mantido fora do assistente é exibido com título, resumo, pedido e efeitos do plano retidos para um leitor sem email:auth_secrets.

Tomar ou renovar o arrendamento de uma tarefa

Dois destinatários nunca trabalham um assunto: o arrendamento nomeia quem trabalha nele até quando (quinze minutos por padrão, até uma hora). Tomá-lo novamente o renova; outro detentor é recusado com TASK_LEASED até a expiração. Uma solicitação de efeitos toma o arrendamento por conta própria. Requer assistant:write.

Devolver o arrendamento

Libera o arrendamento que o chamador detém; um arrendamento detido por outro destinatário é deixado intacto. Requer assistant:write.

Solicitar efeitos em uma tarefa

O destinatário solicita um ou mais efeitos (responder, encaminhar, rotular, adiar, resolver, anotar, requisitar). O nível da delegação decide os tipos permitidos e as permissões os limitam: dentro das permissões em guarded_send ou operate (e os tipos de entrada em triage) os efeitos são executados imediatamente com seus recibos; em draft eles aguardam a aprovação do proprietário; uma permissão falhada escala para o proprietário; um tipo que o nível não permite é recusado. A própria solicitação do proprietário é executada imediatamente. A mesma chave de idempotência responde o primeiro plano novamente. Requer assistant:write.

Parar e perguntar ao proprietário

O responsável faz uma pergunta com a evidência e, quando útil, as opções que vê. O proprietário responde com as interações comuns de escolher ou instruir na decisão que isso cria; o assunto aparece no Today como precisando do proprietário, o lease é liberado, a tarefa aguarda. Requer assistant:write.

Relatar sobre uma tarefa

O que o responsável fez e como terminou: done (o assunto resolve, ou aguarda quando uma resposta ainda é esperada), blocked (o proprietário é perguntado), ou handed back (o proprietário assume e a regra fica desligada neste assunto). Reivindicações são reconciliadas com os recibos que a plataforma escreveu: uma reivindicação sem recibo é registrada como uma reivindicação, nunca como um fato. O lease é liberado. Requer assistant:write.

Leia o que o assistente estabeleceu sobre uma mensagem

O conhecimento que as análises desta mensagem produziram: afirmações (sujeito, predicado, valor com tipo e moeda, base, confiança, validade, evidência), entidades, compromissos e expectativas. Nada é computado no caminho: uma mensagem que o pipeline nunca analisou responde analysed: false com reason (not_enabled quando a caixa de entrada não está no assistente, not_analysed quando a análise ainda não aconteceu). Requer assistant:read.

Extraia os campos que você precisa de uma mensagem com seu próprio schema

Uma chamada de modelo no texto da mensagem (assunto, remetente, corpo) com um schema JSON do chamador de objetos e primitivos (até 8 KB, sem referências): responde data nessa forma, confidence (0 a 1) e evidence_quotes (trechos literais). Armazenado em cache por (mensagem, schema, instruções) então a mesma pergunta custa uma chamada (cached: true depois). Limitado pelo orçamento de modelo da conta (429 quando esgotado, 503 quando a rota do modelo está desligada). E-mails de código de login respondem 403 AUTH_MESSAGE. Corpos acima de 60.000 caracteres respondem 413.

Obter configurações do assistente Mailzero

Retorna o estado de ativação do assistente, sinalizadores de sombra/pausa, versão de consentimento, rota de privacidade, escopo de caixas de correio e todas as caixas de correio que você possui. Requer a permissão 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"
    }
  ]
}

Atualizar configurações do assistente Mailzero

Habilita, pausa, retoma ou delimita explicitamente o processamento do assistente. Enviar mailbox_ids: [] desabilita todas as caixas de correio e cancela uma importação de histórico em andamento. Retomar requer a versão de consentimento atual. O recebimento de e-mail permanece independente. Requer a permissão assistant:write.

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

Consentir e iniciar uma importação de histórico em segundo plano

Registra o consentimento explícito atual de IA, habilita o processamento em segundo plano nas caixas de correio selecionadas do usuário e cria uma importação de histórico recente retomável. O cliente pode fechar imediatamente e consultar GET /api/assistant/backfill. Requer a permissão 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"
  }
}

Obter progresso da importação de histórico em segundo plano

Retorna a fase de varredura/análise, mensagens processadas e totais, porcentagem, ETA adaptativo, estado de pausa e se o aplicativo pode fechar. Requer a permissão 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
  }
}

Tentar novamente mensagens com falha na importação de histórico

Reenfileira falhas terminais da importação mais recente para caixas de correio que permanecem habilitadas para IA. As tentativas automáticas já foram esgotadas antes de uma mensagem aparecer aqui. Requer a permissão assistant:write.

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

Obter a fila de decisões fundamentadas do Today

Retorna as projeções versionadas Now, Needs you, Waiting, Upcoming e Handled recentes com as_of, lag, coverage e warnings. Cada item vincula à sua mensagem de origem; nada aqui envia e-mail. Requer a permissão assistant:read. O e-mail de autenticação (códigos de login, redefinições de senha, links mágicos) nunca vira um assunto e nunca chega a um modelo. Um assunto criado a partir de um e-mail de autenticação antes que esse e-mail fosse mantido fora do assistente é exibido com título, resumo, pedido e efeitos do plano retidos para um leitor sem 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": []
  }
}

Obter um item Work do assistente e o plano atual exato

Retorna o item Work fundamentado, sua Decision aberta e opções, o plano Action atual exato, compromissos e expectativas abertas, interações e recibos. Requer a permissão assistant:read. Um assunto criado a partir de um e-mail de autenticação antes que esse e-mail fosse mantido fora do assistente é exibido com título, resumo, pedido e efeitos do plano retidos para um leitor sem email:auth_secrets.

Ler o resumo da situação de um item de Trabalho

Um documento que um agente lê antes de agir: a situação (status, atenção, recorrência, remetente), a história até agora (cada email dela, analisado ou não), os fatos que as análises estabeleceram (alegações com valor, base e validade, e as entidades), os compromissos e expectativas abertos com o que é aguardado de quem e desde quando, o que já foi resolvido (loops fechados e recibos), a Decisão atual com suas opções, um próximo passo sugerido (a opção recomendada da Decisão quando há uma, caso contrário uma regra: uma promessa atrasada, uma expectativa atrasada para cobrar, a solicitação do remetente para responder), e as mensagens de evidência. Determinístico e barato: nenhuma chamada de modelo. Tokens de agente leem os itens das caixas de correio que operam e os itens entregues a eles.

Ler o resumo da situação para um correspondente

O que saber antes de responder a uma pessoa: o resumo do item de Trabalho ativo mais recente dela nas caixas de correio que você pode ler (ou uma caixa de correio), os outros itens pelos quais ela está responsável, e seus últimos dez emails. brief é null quando nada foi analisado dela ainda.

Leia os fatos por trás de um item de Work

As afirmações e entidades mescladas de cada análise do item (mais recente primeiro vence), mais seus compromissos e expectativas armazenados com seu status. Tokens de agente leem os itens das caixas de entrada que operam e os itens entregues a eles.

Marcar um item Work como aberto

Registra que o proprietário abriu este item Work na versão atual, o que remove o marcador de não lido até que o item mude novamente. Requer o escopo assistant:write.

O que o assistente aprendeu sobre você

As regras de silêncio que o assistente propõe depois que o mesmo remetente ou organização foi ignorado toda vez que voltou, os silêncios em vigor (um remetente, um domínio ou uma situação que o assistente mantém fora de Hoje), cada um com o seu motivo, e as etiquetas confirmadas uma vez, cada uma aplicada ao próximo assunto do mesmo projeto sem perguntar. Aceite uma regra de silêncio pelo endpoint suggestions; esqueça um silêncio com o endpoint mutes, uma etiqueta com o endpoint tags.

Esquecer um silenciamento

O próximo email daquele remetente, domínio ou situação se torna um item novamente.

Esquecer uma etiqueta

Nada mais é aplicado sem perguntar: o próximo assunto desse projeto propõe a etiqueta de novo. Os assuntos que a carregam a mantêm.

Investigue um assunto: o que o registro e os links dizem

Lê, naquele instante, os fatos que a infraestrutura pública mantém sobre o domínio do remetente (sua data de registro e registrador, sua postura SPF e DMARC, se recebe email), para onde cada link da mensagem de origem realmente vai (os redirecionamentos seguidos um salto por vez, o host final e os fatos do seu domínio), e o que cada anexo realmente é (seus primeiros bytes em comparação com o nome e o tipo declarado). Responde o dossiê com os sinais que os fatos adicionam (um domínio registrado dias atrás, um link que chega em outro lugar, um domínio do remetente que não protege nada, um programa nomeado como um documento). Sem fornecedor, sem conta, nada armazenado; uma consulta que falha é um fato por si só.

Quem está por trás de um assunto: a organização, as pessoas envolvidas, o histórico

Responde a ficha do remetente de um assunto: a organização do remetente como o perfil de domínio armazenado a conhece (nome, razão social, categoria, site, data de registro, postura de email; null para um domínio de email compartilhado como gmail.com ou um domínio nunca analisado, e nunca uma análise ao vivo), as pessoas que as mensagens da história carregam em from, to e cc com seus papéis e se pertencem à mesma organização (as próprias caixas do leitor excluídas), e a relação: quanto email veio deste endereço nas caixas do leitor (contado até 50), quando pela primeira e última vez, os outros assuntos do remetente e os assuntos levantados por colegas do mesmo domínio. Requer o scope assistant:read.

Registrar uma Decision humana isolada

Escolha uma opção, dê uma instrução, assuma o controle, adie, ignore, corrija, reporte o veredito de confiança (phishing ou legítimo), ou aprove ou rejeite um plano em espera (um plano aprovado executa imediatamente, com seus recibos na resposta). A chamada é isolada por work_item_version e repetida de forma idempotente por idempotency_key. Escolher ou instruir prepara um rascunho exato que ainda passa pelo fluxo normal de resposta; este endpoint nunca envia e-mail. Requer a permissão assistant:write.

Obter a visualização exata da ação por ID opaco

Retorna a identidade de resposta exata, destinatários, corpo, compromissos e efeitos colaterais de um plano de ação preparado, além de sua expiração e revisão de origem, para que um cliente possa mostrar o que acontecerá antes que o usuário envie através do endpoint de resposta existente com assistant_plan_id. Requer o scope assistant:read.

Obter atividade do assistente com conteúdo minimizado

Lista as interações e recibos recentes atribuídos ao chamador sem os corpos das mensagens. Requer o scope assistant:read.

Exportar dados derivados do assistente

Exporta análises, reivindicações aceitas, decisões, interações, recibos e uso do modelo como um anexo JSON. Nunca inclui os corpos de e-mail de origem ou bytes de anexos. Requer o scope assistant:write. Também requer email:auth_secrets (caso contrário, 403 INSUFFICIENT_SCOPE): o estado derivado pode conter o que o assistente extraiu de e-mails de autenticação antes que esses e-mails fossem mantidos fora dele.

Excluir dados derivados do assistente

Exclui de forma idempotente inteligência derivada, trabalhos, uso do modelo, dispositivos, importações e configurações enquanto preserva o e-mail de origem. Requer a permissão assistant:write.

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

Registrar um dispositivo para alertas Now ocultados

Registra ou rotaciona um token push criptografado para uma instalação de aplicativo e ambiente. Apenas o aplicativo nativo chama isso; requer um assistente ativo e a permissão assistant:write.

Revogar um registro de dispositivo

Revoga todos os registros push de uma instalação, por exemplo ao sair. Requer a permissão assistant:write.

Verifique a integridade do DNS do e-mail (MX, SPF, DMARC, DKIM)

Verifica a configuração DNS de email para um domínio: registros MX, SPF, DMARC e DKIM. Detecta automaticamente o provedor de e-mail dos registros 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"

Obtenha a integridade da entregabilidade de e-mail no escopo do proprietário

Separa a prontidão de autenticação determinística, resultados de entrega ponderados pelo destinatário em 30 dias, estado de segurança da conta e posicionamento medido do fornecedor. A pontuação de prontidão não é uma probabilidade da Caixa de entrada e o posicionamento não medido é retornado como not_tested.

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

Configurar e-mail em um domínio

Pré-configure o DNS de e-mail em um domínio (opcional). Isso é chamado automaticamente por create_mailbox quando necessário. Passe force=true para substituir o provedor de e-mail existente (Google Workspace, Fastmail, Proton).

Remover e-mail de um domínio

Remova o email de um domínio, exclua todas as caixas de correio e mensagens e defina emailEnabled como falso. Altera o e-mail do domínio inteiro, portanto um token confinado a caixas de correio recebe 403 MAILBOX_CONFINED.

Verifique o status do DNS do e-mail

Verifique o status de verificação de DNS do email para um domínio. Retorna se o domínio está verificado e pronto, detalhes do registro DNS e contagem de caixas de correio.

Crie uma caixa de correio em domani.run

Crie um endereço de e-mail gratuito em domani.run (por exemplo, hello@domani.run). Não é necessária propriedade de domínio. Limitado a 1 caixa de correio @domani.run gratuita por usuário. Muitas lesmas comuns são reservadas.

Listar todas as caixas de correio

Liste todas as caixas de correio que o identidade solicitante pode acessar em todos os domínios, incluindo permissões de espaço de trabalho.

Crie uma caixa de correio

Crie um endereço de e-mail (caixa de correio). Forneça um endereço completo como "hello@mysite.com". O Email DNS é configurado automaticamente na primeira utilização. Passe force=true para substituir um provedor de e-mail existente. A capacidade da caixa de correio de domínio personalizado é determinada pela conta ativa ou plano de espaço de trabalho. Cada conta pode criar uma caixa de correio gratuita @domani.run separadamente com POST /api/email. Passe workspace_id para criar a caixa de correio dentro de um espaço de trabalho de sua propriedade. Para um domínio personalizado, isso adota explícita e atomicamente o domínio e todas as suas caixas de correio irmãs sem escopo nesse espaço de trabalho; um domínio nunca pode ser dividido entre espaços de trabalho. Passe kind="hosted" para criar uma caixa de correio IMAP/SMTP real em seu próprio domínio (conecte Apple Mail, Thunderbird ou qualquer cliente) em vez da caixa de correio API padrão (enviar/receber via API + webhooks). As caixas de correio hospedadas retornam registros DNS para publicação, configurações do cliente de email e uma senha de aplicativo única. Requer um domínio que você possui.

Listar todas as caixas de correio

Liste todas as caixas de correio que o identidade solicitante pode acessar, incluindo permissões de espaço de trabalho. O mesmo que GET /api/email.

Obtenha detalhes da caixa de correio

Obtenha detalhes de uma caixa de correio específica por meio de seu endereço de e-mail completo (codificado em URL, por exemplo, hello%40mysite.com).

Atualizar caixa de correio

Atualize o nome de exibição, o URL do webhook ou o endereço de email de encaminhamento de uma caixa de correio pelo endereço de email completo. Defina como nulo para desabilitar/limpar.

Excluir uma caixa de correio

Exclua uma caixa de correio pelo endereço de e-mail completo. Requer confirm=true no corpo. Sem confirmação, retorna uma visualização com message_count.

Envie um e-mail

Envie um e-mail de uma caixa identificada pelo endereço completo. O servidor executa primeiro uma política obrigatória e versionada: nega falhas objetivas de segurança e retorna como avisos os problemas de reputação e qualidade do conteúdo. Para uma resposta colaborativa em thread, passe o lease de composição, o reply_version observado e uma chave de idempotência estável; o servidor rejeita atomicamente respostas obsoletas ou duplicadas imediatamente antes do envio. Máximo de 20 destinatários únicos por mensagem. Limite: 100 destinatários por hora por caixa.

Simular um e-mail de saída

Execute a política do lado do servidor com versão exata usada pelo endpoint de envio sem enviar ou consumir cota de email. Links públicos de autenticação HTTPS em domínios de terceiros são permitidos com um aviso de reputação. URLs locais/privados, links de autenticação não HTTPS e anexos executáveis ​​são bloqueados; corpos acima de 102 KB produzem um aviso de recorte.

Listar e-mails

Liste e-mails em uma pasta canônica ou visualização virtual. O padrão é Caixa de entrada. A localização da pasta é independente da direção da mensagem e do veredicto de spam. O e-mail de autenticação (OTPs/códigos de verificação, redefinições de senha, links mágicos) é marcado como security: "auth". Tokens sem o escopo email:auth_secrets veem aquelas mensagens com assunto e corpo OCULTOS (redacted: true) - os metadados (de, data) permanecem visíveis. Os filtros subject, q e attachments correspondem ao que quem chama pode ler: sem o escopo, essa mensagem só corresponde pelo assunto e pelo corpo ocultos, então uma busca pelo código que ela contém não encontra nada.

Buscar emails por significado e por palavras

Busca nas caixas de entrada que você pode ler, ou em uma caixa de entrada com mailbox. Híbrido por padrão: o embedding da mensagem (pgvector, cosseno) e o índice de palavras ponderadas são fundidos por rank recíproco com um pequeno impulso de recência, em uma única instrução; why indica qual ramo correspondeu. Operadores do Gmail em 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 ou -from: para excluir, a OR b. Uma consulta feita apenas de operadores lista as mensagens correspondentes da mais recente para a mais antiga (why: filter). Códigos e links de login, spam e emails do sistema nunca são indexados; caixas de entrada listadas em search_opt_out_mailbox_ids do assistente são buscadas apenas por palavras. Um token vinculado a uma identidade de agente busca apenas as caixas de entrada que seu agente opera. Requer email:read. Sem email:auth_secrets, o e-mail de autenticação recebido é deixado de fora antes da classificação: nenhuma palavra, operador ou filtro corresponde a ele, então uma busca por um código de login não encontra nada.

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

Iniciar conexão de uma caixa de entrada do Gmail

Retorna a URL de consentimento do Google vinculada à sua conta e ao limite de importação. Abra-a em um navegador; após o consentimento, a caixa de entrada se torna uma caixa de correio conectada em seu próprio endereço, os emails recebidos após o limite são importados (padrão: as últimas 24 horas), e novos emails seguem conforme chegam. Nunca a caixa de entrada inteira: amplie depois com POST /api/emails/{address}/import. Requer email:write. O OAuth do Google deve estar configurado no servidor.

Comece a conectar uma caixa de entrada do Outlook

Retorna a URL de consentimento da Microsoft vinculada à sua conta e ao limite de importação. Abra-a em um navegador; após o consentimento, a caixa de entrada se torna uma caixa de correio conectada em seu próprio endereço, o email recebido após o limite é importado (padrão: as últimas 24 horas), e novos emails chegam conforme são recebidos. Nunca a caixa de entrada inteira: amplie depois com POST /api/emails/{address}/import. Requer email:write. O OAuth da Microsoft deve estar configurado no servidor.

Lista as formas como uma caixa de entrada pode ser conectada

Uma linha por provedor (Gmail, Outlook, qualquer caixa de entrada por encaminhamento, um endereço hospedado aqui): como a conexão começa (uma tela de consentimento, uma regra de encaminhamento, um endereço criado), o que a conexão pode fazer (ler, ou ler e escrever), se importa emails mais antigos, e se este servidor está configurado para isso. Mostre um botão de conectar apenas quando configured for true; reason nomeia a variável ausente para o operador. Requer email:read.

Conectar uma caixa de entrada por encaminhamento

Cria uma caixa de correio conectada no próprio endereço da caixa de entrada e responde com um endereço de encaminhamento no domínio de encaminhamento da plataforma, com os passos para Gmail, Outlook e outros provedores. Adicione uma regra de encaminhamento no provedor; o que chega naquele endereço é desembrulhado (remetente original, data, assunto) e armazenado sob a caixa de correio conectada. O Gmail pede ao endereço de encaminhamento para confirmar: o código e o link aparecem na conexão. O primeiro email que volta, ou uma sonda (POST /api/emails/{address}/connector/verify), torna a conexão ativa. Apenas emails novos chegam desta forma; emails mais antigos não podem ser importados. Requer email:write. O domínio de encaminhamento deve estar configurado no servidor.

Enviar uma sonda através da regra de encaminhamento

Envia um email para a caixa de entrada conectada; quando a regra de encaminhamento o traz de volta ao endereço de encaminhamento, a conexão se torna ativa. Apenas para uma conexão por encaminhamento. Requer email:write.

Ler a conexão de uma caixa de correio conectada

Tipo, status, o limite de importação, a fase de sincronização (a varredura de importação, depois histórico), o progresso da importação (verificados, copiados, a analisar, analisados), a última sincronização e o último erro. Requer email:read. A confirmação de encaminhamento (o código e o link do Gmail) é e-mail de autenticação: sem email:auth_secrets, o código e a url dela são null e ela traz redacted: true. Um token confinado a caixas de correio só encontra as próprias caixas de correio (caso contrário, 404).

Desconectar uma caixa de correio conectada

Remove as próprias cópias da pessoa (mensagens, anexos, linhas de busca, trabalhos pendentes) e a credencial; mantém a linha da caixa de correio, o link marcado como desconectado, e o que os agentes fizeram (recibos). Apenas uma caixa de correio conectada pode ser desconectada. Requer email:write.

Importar emails mais antigos de uma caixa de correio conectada

Amplia a importação para uma data anterior: uma nova execução de importação copia os emails entre o novo limite e o atual, em ordem de chegada, sob seu próprio limite de custo. Recusado enquanto uma varredura de importação ainda está em execução. Requer email:write.

Buscar em uma caixa de entrada por significado e por palavras

A mesma busca que GET /api/emails/search, restrita a esta caixa de entrada. Requer email:read. Sem email:auth_secrets, o e-mail de autenticação recebido é deixado de fora antes da classificação: nenhuma palavra, operador ou filtro corresponde a ele, então uma busca por um código de login não encontra nada.

Listar as conversas de uma caixa de correio

Mensagens agrupadas da forma que clientes de email as agrupam: uma resposta se junta à thread da mensagem que ela responde (In-Reply-To, depois a cadeia References), email sem cabeçalhos utilizáveis se junta à thread mais recente com o mesmo assunto e um correspondente em comum dentro de trinta dias, todo o resto inicia uma thread cujo id é o id de sua primeira mensagem. Threads são ordenadas por última atividade; lixeira e spam nunca participam a menos que nomeados como a pasta. folder=inbox|archive|sent mantém as threads que têm uma mensagem lá mas ainda conta a conversa inteira.

Ler uma conversa, mensagem mais antiga primeiro

Todas as mensagens da thread (lixeira incluída, para que nada falte da história) com seu texto, mais antiga primeiro, mais os participantes e a contagem de não lidas. Email de autenticação é censurado da forma que leituras de mensagem são.

Transmitir eventos da caixa de entrada (server-sent events)

Retorna text/event-stream. Sem um cursor a transmissão começa no presente; com since (um cursor de /api/email/changes ou o id de qualquer evento anterior) primeiro reproduz cada mudança após aquele ponto, depois segue o diário da caixa de entrada ao vivo: cada frame carrega o tipo da mudança como o nome do evento (message.received, message.updated, message.deleted, message.moved, message.status, mailbox.resync_required, assistant.item.delegated, assistant.item.recalled, ...), a mudança como dados JSON com seu cursor retomável, e esse mesmo cursor como o id do frame. O primeiro frame é ready com o cursor para retomar; um comentário keep-alive chega a cada 20 segundos; a conexão fecha após cerca de 5 minutos com um frame close e uma dica retry:. Reconecte com Last-Event-ID (ou since) para retomar sem lacuna e sem duplicata. Tokens de agente são confinados às caixas de entrada que o agente opera. Uma entrada sobre um item de trabalho criado a partir de um e-mail de autenticação traz title e ask ocultos para um token sem email:auth_secrets.

Listar pastas e contagens de e-mail

Retorna contagens derivadas do servidor para pastas do sistema e visualizações virtuais, além de recursos de ciclo de vida para o back-end da caixa de correio.

Aplicar uma ação de ciclo de vida às mensagens

Mova, restaure, marque como lida, marque com estrela ou exclua permanentemente até 100 IDs de mensagens explícitas. Mover para a Lixeira é reversível. A exclusão permanente requer email:delete e aceita apenas mensagens que já estão na Lixeira. Cada resposta é um recibo de operação durável com um resultado por ID solicitado. Forneça uma chave estável no cabeçalho padrão Idempotency-Key ou no campo JSON legado idempotency_key e reutilize-a após o tempo limite; uma nova tentativa exata retorna o recibo armazenado sem outra mutação. Se ambos os formulários forem fornecidos, eles deverão corresponder. Reutilizar uma chave com uma solicitação diferente retorna 409. Quando omitido, o servidor cria uma chave e a retorna no corpo e no cabeçalho Idempotency-Key. Retorna 207 quando apenas parte do lote é bem-sucedida.

Marcar mensagens como lidas ou não lidas

Endpoint de compatibilidade para atualizações de estado de leitura seguras para novas tentativas. Retorna o recibo de operação canônico durável por item mais a contagem herdada. Forneça e reutilize o cabeçalho Idempotency-Key ou o campo idempotency_key de compatibilidade após o tempo limite.

Excluir mensagens em massa

Endpoint de compatibilidade que move mensagens com segurança para a Lixeira. Retorna o recibo de operação canônico durável por item mais a contagem herdada. Forneça e reutilize o cabeçalho Idempotency-Key ou o campo idempotency_key de compatibilidade após o tempo limite.

Receba uma mensagem

Busque uma única mensagem por ID de uma caixa de correio identificada por seu endereço de e-mail completo. Mensagens classificadas como correio de autenticação (OTP, redefinição de senha, link mágico) retornam com assunto/corpo oculto, a menos que o token tenha o escopo email:auth_secrets.

Excluir uma mensagem

Mova uma mensagem para a Lixeira. Isto é reversível. Use a ação de ciclo de vida com delete_permanently e um token email:delete para apagar uma mensagem que já está na Lixeira.

Responder a uma mensagem

Responda a uma mensagem em uma caixa identificada pelo endereço completo. Os cabeçalhos da thread são preenchidos automaticamente, e o original é citado abaixo da resposta como fazem os clientes de e-mail (linha de atribuição no idioma da conta, linhas > no texto, um bloco gmail_quote no HTML), a menos que quote seja false. Clientes colaborativos devem passar o lease de composição, o reply_version observado e uma chave de idempotência estável; o servidor rejeita atomicamente uma resposta obsoleta ou duplicada imediatamente antes do envio.

Encaminhar uma mensagem

Encaminhe uma mensagem de uma caixa de correio identificada pelo seu endereço de e-mail completo para outro destinatário. O encaminhamento de mensagens de autenticação (OTP, redefinição de senha, link mágico) requer o escopo email:auth_secrets - isso exfiltraria o segredo.

Obtenha informações do avatar da caixa de correio

Retorna o URL do Gravatar (se definido) e o link de inscrição para uma caixa de correio identificada pelo seu endereço de e-mail completo.

Obter configuração do webhook da caixa de correio

Retorna a URL do webhook, o segredo de assinatura, os nomes dos cabeçalhos de autenticação configurados e o status de uma caixa de correio. Os valores de cabeçalho nunca são retornados.

Definir webhook da caixa de correio

Configure o destino HTTPS para eventos de caixa de correio assinados por HMAC: o e-mail de entrada por padrão, mais (opcional via events) o veredito de entrega do e-mail enviado A PARTIR DA caixa de correio: uma devolução chega ao remetente segundos depois de o envio ser aceito, em vez de viver apenas no histórico da mensagem. As entregas de entrada em tempo real são armazenadas de forma durável, tentadas imediatamente e repetidas até três vezes. Cada tentativa inclui X-Domani-Delivery-Attempt começando em 1. Os valores opcionais de autorização ou X-API-Key são criptografados e nunca retornados; os operadores humanos devem enviá-los fora do contexto do modelo por meio das opções de variável de 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"]}'

Remover webhook da caixa de correio

Remova o URL do webhook e o segredo de assinatura de uma caixa de correio. Os e-mails recebidos serão armazenados apenas.

Alternar segredo de assinatura do webhook

Gere novamente o segredo de assinatura HMAC-SHA256 para um webhook de caixa de correio. O antigo segredo é imediatamente invalidado.

Testar webhook de caixa de correio

Envie uma carga de teste assinada para o URL do webhook da caixa de correio. Retorna o status HTTP e se a entrega foi bem-sucedida. Os testes não são repetidos; as entregas de entrada ao vivo são repetidas até três vezes.

Listar aliases de caixa de correio

Liste todos os endereços de alias entregues em uma caixa de correio. Os aliases permitem que vários endereços (vendas@, olá@, contato@) compartilhem uma caixa de entrada sem usar um slot de caixa de correio.

Adicionar um alias de caixa de correio

Adicione um endereço de alias que seja entregue nesta caixa de correio, sem usar um slot de caixa de correio. O alias deve estar no mesmo domínio que a caixa de correio. Forneça um slug simples ("sales") ou um endereço completo ("sales@mysite.com").

Remover um alias de caixa de correio

Remova um alias de uma caixa de correio. O e-mail para esse endereço deixa de ser entregue.

Obtenha as configurações do cliente de e-mail (hospedado)

Obtenha configurações de conexão IMAP/SMTP para uma caixa de correio hospedada, para configurar Apple Mail, Thunderbird ou qualquer cliente de email. Nome de usuário é o endereço completo; a senha é uma senha de aplicativo (crie uma com POST /api/emails/{address}/credentials). Apenas caixas de correio hospedadas.

Listar senhas de aplicativos (hospedados)

Liste as senhas de aplicativo de uma caixa de correio hospedada. Os segredos são mostrados apenas uma vez na criação; isso retorna apenas rótulos e metadados. Apenas caixas de correio hospedadas.

Crie uma senha de aplicativo (hospedado)

Crie uma senha de aplicativo para uma caixa de correio hospedada, usada como senha em um cliente de email (IMAP/SMTP). O segredo é retornado uma vez - armazene-o agora. Apenas caixas de correio hospedadas.

Revogar uma senha de aplicativo (hospedado)

Revogar uma senha de aplicativo. Qualquer cliente de e-mail que o utilize interrompe a conexão imediatamente. Apenas caixas de correio hospedadas.

Sinalizar uma mensagem para um humano

Escale uma mensagem para o humano da conta (ou limpe o sinalizador com clear=true). Define needs_human na mensagem, retém a conversa no status needs_human e dispara o webhook email.escalated + notificação no aplicativo. A primitiva do produto por trás de 'answer the easy ones, stop on the one the human must decide' (responda as fáceis, pare naquela que o humano precisa decidir).

Definir um lembrete de follow-up

Defina (ou limpe com clear=true) um lembrete único de follow-up em uma mensagem. Quando remind_at chega e a mensagem ainda está sem resposta (entrada: nenhuma resposta enviada; saída: nenhuma resposta de entrada recebida), email.reminder_due dispara como webhook + notificação no aplicativo e o lembrete se limpa sozinho.

Listar contatos

A agenda de contatos da conta, alimentada automaticamente pelo tráfego de e-mail: correspondentes, contagens de mensagens, última atividade e notas. Por padrão, os mais recentemente ativos primeiro (order=recent), para exibição: um contato que recebe e-mail novo durante uma varredura paginada passa à frente do cursor, então essa varredura pode pulá-lo. Para sincronizar a agenda inteira, passe order=created: os mais antigos primeiro pela data de criação e depois pelo id, uma chave que nunca muda, então cada contato que existe durante toda a varredura volta exatamente uma vez e os contatos criados nesse meio-tempo vêm no final. Um cursor só continua a ordem de onde veio (400 INVALID_CURSOR caso contrário). Agrega dados de todas as caixas de correio, portanto tokens confinados a caixas de correio são negados (400 MAILBOX_CONFINED).

Criar ou atualizar um contato

Salve um contato: defina um nome de exibição e anexe notas ('prefers short emails', 'decision maker at Acme'). O tráfego de e-mail continua alimentando as contagens de mensagens de qualquer forma.

Excluir um contato

Remova um contato da agenda de contatos. O tráfego de e-mail o recriará como contato automático se a pessoa escrever novamente.

Listar regras de e-mail de entrada

Liste as regras de filtragem de entrada de uma caixa de correio, na ordem de prioridade em que são aplicadas (a primeira correspondência vence).

Adicionar uma regra de e-mail de entrada

Adicione uma regra executada em mensagens recebidas que correspondam a um campo (from/to/subject/body). Ações: drop, mark_read, forward (action_arg = endereço), webhook_only (ignora o encaminhamento) e label (action_arg = rótulo). As regras são aplicadas por prioridade crescente; a primeira correspondência vence.

Remover uma regra de e-mail de entrada

Remova uma regra de filtragem de entrada de uma caixa de correio.

Definir domínio genérico

Encaminhe cada e-mail enviado para um endereço sem correspondência no domínio para uma caixa de correio designada. Qualquer coisa que não corresponda a uma caixa de correio, subendereço ou alias será incluída no pega-tudo. A caixa de correio já deve existir no domínio. Altera o e-mail do domínio inteiro, portanto um token confinado a caixas de correio recebe 403 MAILBOX_CONFINED.

Limpar domínio genérico

Remova o pega-tudo em um domínio. Os e-mails para endereços não correspondentes serão descartados novamente. Altera o e-mail do domínio inteiro, portanto um token confinado a caixas de correio recebe 403 MAILBOX_CONFINED.

Sincronizar incrementalmente uma caixa de correio

Chame sem cursor para capturar uma linha de base antes de um instantâneo completo limitado. Em seguida, passe next_cursor para reproduzir as mutações que aconteceram durante e após esse instantâneo. Os cursores são opacos, assinados, vinculados à caixa de correio e expiram após 30 dias. As notificações push são apenas dicas de invalidação; este diário é a fonte de recuperação durável. Uma entrada sobre um item de trabalho criado a partir de um e-mail de autenticação traz title e ask ocultos para um token sem email:auth_secrets.

Listar endereços suprimidos

Liste endereços em sua lista de supressão - devoluções definitivas e reclamações (ingeridas automaticamente de eventos de entrega), além de entradas manuais. Os envios para esses endereços são ignorados. Paginado por cursor.

Adicione uma supressão

Adicione manualmente um endereço à sua lista de supressão para que envios futuros o ignorem. Devoluções permanentes e reclamações são adicionados automaticamente; use isso para endereços que você deseja parar de enviar por e-mail. Idempotente.

Remover uma supressão

Remova um endereço da sua lista de supressão para poder enviá-lo novamente por e-mail (por exemplo, depois que o destinatário consertar sua caixa de correio).

Solicitar uma transferência de propriedade do espaço de trabalho

Somente proprietário. Envia um link de aceitação de 48 horas para um membro existente. Nada se move até que o membro autenticado aceite.

Revogar uma transferência de propriedade pendente

Aceitar a propriedade do espaço de trabalho

Somente alvo. Transfere atomicamente o espaço de trabalho, domínios com escopo e caixas de correio; o proprietário anterior torna-se administrador e o pagador existente permanece inalterado.

Crie uma nova conta

Começa a criar uma nova conta (ou autentica uma existente) enviando um link de login por e-mail; nenhuma chave de API é retornada aqui. Uma pessoa que clica nesse link em um navegador chega ao painel já autenticada. Uma CLI ou um agente sem sessão de navegador deve usar em vez disso o fluxo de login por dispositivo (POST /api/auth/cli e depois consultar GET /api/auth/cli/poll), que envia por e-mail a mesma aprovação e devolve uma chave de API quando aprovada - a resposta indica isso em next_steps. Passar um código ref vincula permanentemente o novo usuário a um indicador - o indicador ganha uma comissão sobre todas as futuras compras de domínios desse usuário.

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

Envie um e-mail de login com link mágico

Envia um link de login para o e-mail fornecido. Se o usuário não existir, crie primeiro uma conta. O link mágico redireciona para o painel com credenciais de autenticação. Para acesso programático à API, use POST /api/auth/register para obter uma chave de API diretamente.

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

Verifique um token de link mágico

Valida o token do link mágico e redireciona para o painel com credenciais de autenticação. Usado pelo e-mail de link mágico - normalmente não chamado diretamente pelos agentes. Os agentes devem usar POST /api/auth/register.

Gerar um código de login de uso único entre hosts

Somente no navegador: permite que uma pessoa conectada em domani.run ou mailzero.run retome a sessão no outro host sem um segundo link mágico. Retorna uma URL cujo fragmento carrega um código de uso único, válido por 60 segundos e vinculado ao host; o código nunca é registrado em log nem enviado em uma string de consulta. Não tem utilidade fora de uma sessão de navegador, por isso não é exposto como ferramenta de agente.

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

Resgatar um código de login de uso único entre hosts

Somente no navegador: chamado pela página /auth/handoff no host de destino para trocar o código do fragmento da URL por uma sessão, exatamente como GET /api/auth/verify faz com um link mágico. O código deve corresponder ao Host em que esta solicitação chegou. Não é uma ferramenta de agente.

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

Obtenha detalhes da conta atual

Retorna as informações da conta do usuário autenticado, incluindo e-mail, status do pagamento, status das informações de contato, código de referência e contagens de uso. Os agentes devem chamar isso após a autenticação para verificar has_payment_method e has_contact antes de tentar compras.

{
  "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"

Atualizar preferências da conta

Atualize o método de pagamento preferencial do usuário autenticado e/ou localidade BCP 47. As respostas da API permanecem estruturadas e não são traduzidas.

Excluir conta (bloqueada enquanto os domínios estão retidos)

Exclua permanentemente a conta, os tokens, os webhooks, as caixas de correio e outros dados do aplicativo do usuário autenticado. Os domínios registrados NÃO são excluídos com a conta: a solicitação falha com 409 HAS_DOMAINS até que todos os domínios sejam transferidos. Esta ação não pode ser desfeita.

Obtenha um estado de ativação verdadeiro e as próximas ações recomendadas

Retorna marcos de produtos derivados do servidor e próximas ações com reconhecimento de capacidade. A criação de token, o uso de token, as visualizações de página e o estado da lista de verificação do cliente são deliberadamente excluídos.

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

Ignorar ou restaurar a orientação inicial

Armazena apenas a preferência de apresentação. Ele não pode completar um marco do produto.

Obtenha informações de contato do registrante

Retorna as informações de contato WHOIS do titular do usuário autenticado. Opcionais para compras (enquanto não forem definidas, o contato da Domani mantém os novos domínios em nome do usuário), obrigatórias para uma transferência de entrada.

{
  "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"

Definir informações de contato do registrante

Define ou atualiza suas informações de contato WHOIS do titular. Opcionais para compras, obrigatórias para uma transferência de entrada. Elas se tornam o contato titular e de cobrança dos seus domínios: enquanto não forem definidas, o contato da Domani os mantém em seu nome. Ao atualizar, o novo contato é enviado a todos os seus domínios ativos nos registradores que aceitam alterações de contato, o que torna você o titular deles; o registrador pode pedir por e-mail que você o confirme em até 15 dias.

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

Reenviar verificação de e-mail de contato

Reenvie o e-mail de verificação para o endereço de contato da conta. Limitado a um envio a cada 15 minutos por endereço.

Listar os dispositivos conectados

Cada navegador, app móvel e terminal conectado à conta, com a sessão de quem chama primeiro (current). Cada login abre sua própria sessão, então entrar em um novo dispositivo nunca desconecta outro. A localização é de onde o dispositivo entrou (país e cidade pelo IP), ausente quando desconhecida. Chaves de API não são sessões: liste-as com 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"

Desconectar todos os outros dispositivos

Desconecta todas as sessões da conta, exceto a que faz a solicitação. Esses dispositivos precisarão entrar de novo na próxima solicitação. As chaves de API não mudam.

{
  "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"

Desconectar um dispositivo

Desconecta uma sessão. current indica a sessão que faz a solicitação (sair não exige escopo); qualquer outra sessão exige 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"

Listar os tokens de API de uma identidade de agente

Os tokens vinculados a esta identidade de agente (chaves mascaradas, escopos, confinamento de caixa de correio, último uso). Um token vinculado a agente é a visão daquele agente sobre cada assistente e superfície de email.

Dar a um agente sua própria chave de API em uma chamada

Cria um token vinculado a esta identidade de agente, confinado às caixas de correio que o agente opera, com os escopos mínimos que um agente precisa (assistant:read, assistant:write, email:read, email:write). Com essa chave o agente lê apenas seu próprio Today, suas caixas de correio e os itens entregues a ele; nomear outro agente responde 403 e rotas exclusivas do proprietário (configurações, backfill, exportação) recusam. A chave completa é retornada apenas nesta resposta. Requer tokens:write. Um agente que não opera nenhuma caixa de correio não recebe escopos de e-mail por padrão, e pedi-los responde 400 AGENT_MAILBOXES_REQUIRED: uma chave sem caixas de correio alcançaria todas as caixas de correio da conta.

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

Revogar um token de API de um agente

Revoga um token vinculado a esta identidade de agente. Ele para de funcionar imediatamente. Requer tokens:write.

Liste seus tokens de API

Retorna todos os tokens de API do usuário autenticado. As chaves são mascaradas por segurança (primeiros 12 + últimos 4 caracteres visíveis). Use isto para auditar tokens ativos.

{
  "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"

Crie um novo token de API

Cria um novo token de API. A chave completa é retornada apenas nesta resposta - armazene-a com segurança. Você pode criar vários tokens para separar o acesso de diferentes aplicativos.

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

Revogar um token de API

Revoga permanentemente um token de API. Quaisquer aplicativos que utilizem esse token perderão imediatamente o acesso. Esta ação não pode ser desfeita.

{
  "success": true
}

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

Listar eventos de auditoria de segurança

Retorna a trilha de auditoria de segurança da conta, primeiro a mais recente: ciclo de vida do token (criado, revogado, tentativas de escalonamento), negações de gastos máximos e max_price, cobranças, solicitações de pagamento e exclusões de contas bloqueadas. Use-o para monitorar o que os tokens dos seus agentes estão fazendo.

{
  "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"

Listar webhooks

Liste todos os endpoints de webhook configurados para sua conta. Retorna URL, eventos inscritos e status ativo para cada webhook. Os segredos nunca são retornados após a criação. Um token confinado a caixas de correio vê apenas os webhooks confinados às próprias caixas de correio.

{
  "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"

Criar webhook

Registre um novo endpoint de webhook HTTPS. Os valores opcionais de autorização ou X-API-Key são criptografados em repouso e incluídos em cada entrega. O segredo de assinatura é retornado apenas uma vez. Máximo de 5 webhooks por conta. Um webhook criado por um token confinado a caixas de correio fica confinado às mesmas caixas: não recebe nenhum evento de e-mail de outra caixa de correio.

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

Atualizar webhook

Atualize o URL de um webhook, eventos inscritos, status ativo ou cabeçalhos de autenticação criptografados. Envie apenas os campos que deseja alterar. Um token confinado a caixas de correio só alcança os webhooks confinados às próprias caixas de correio (caso contrário, 404).

Excluir webhook

Exclua um ponto de extremidade do webhook. Todas as entregas pendentes serão canceladas. Isto não pode ser desfeito. Um token confinado a caixas de correio só alcança os webhooks confinados às próprias caixas de correio (caso contrário, 404).

Listar entregas de webhook

Obtenha tentativas de entrega recentes de um webhook. Mostra o tipo de evento, o status HTTP, o número de tentativas e quaisquer erros. Útil para depurar entregas com falha. Um token confinado a caixas de correio só alcança os webhooks confinados às próprias caixas de correio (caso contrário, 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."
}

Reproduzir uma entrega de webhook

Clone e entregue novamente imediatamente um evento de webhook imutável. A carga útil do evento e o ID do evento permanecem idênticos; a assinatura HMAC recebe um novo carimbo de data/hora. Uma chave de idempotência obrigatória garante que as novas tentativas do chamador nunca sejam enviadas duas vezes. Um token confinado a caixas de correio só alcança os webhooks confinados às próprias caixas de correio (caso contrário, 404). Uma exceção à carga útil idêntica: um assunto copiado de um e-mail de autenticação é enviado oculto, pois a URL do webhook pode ter mudado desde o primeiro envio.

Listar tipos de eventos de webhook

Liste todos os tipos de eventos de webhook disponíveis com descrições. Nenhuma autenticação necessária.

{
  "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

Listar notificações

Liste suas notificações no aplicativo com paginação baseada em cursor. Inclui eventos de transações, atualizações de listagem e alertas do sistema. Requer escopo notifications:read. Uma notificação escrita antes de os assuntos de e-mail serem ocultados na gravação é lida com o assunto do e-mail de autenticação oculto, em body e data.subject, para um token sem email:auth_secrets.

Obtenha contagem de notificações não lidas

Endpoint leve para pesquisa de contagem de notificações não lidas. Requer escopo notifications:read.

{
  "unread_count": 3
}

Marcar notificação como lida

Marcar uma única notificação como lida. Requer escopo notifications:read.

Marcar todas as notificações como lidas

Marcar todas as notificações não lidas como lidas. Requer escopo notifications:read.

Obtenha preferências de notificação

Retorna as preferências de notificação do usuário para cada categoria e canal (in_app, email). As preferências ausentes são ativadas por padrão. Requer o escopo notifications:read.

Atualizar preferências de notificação

Atualize as preferências de notificação para categorias e canais específicos. Requer escopo notifications:read.