Documentación de Mailzero

Listar las delegaciones permanentes

Las reglas de delegación permanente del propietario en orden: nombre, el predicado de coincidencia, el asignatario (una identidad de agente o un miembro del espacio de trabajo), el nivel de autonomía, cuántas veces coincidió cada una. Requiere assistant:read; un token de agente es rechazado.

Crear una delegación permanente

Entregar un tipo de asunto a un agente o una persona una vez. match es un predicado explícito, nunca una llamada de modelo: cualquiera de senderAddress, senderDomain, organisation, workKeyPrefix, senderKind, mailboxIds, labels, subjectPattern (anclado, sin distinción de mayúsculas y minúsculas), minOccurrences, minConfidence (la probabilidad del clasificador calibrado en una etiqueta category:, de 0,5 a 1); cada condición declarada debe cumplirse. Las reglas están ordenadas y la primera coincidencia gana; el nivel es observe a menos que se indique lo contrario. Una regla coincidente entrega el siguiente elemento coincidente al asignatario, se lo comunica mediante el aviso de delegación, y Today muestra por qué. Requiere assistant:write; un token de agente es rechazado.

Cambiar una delegación permanente

Renombrar, habilitar o deshabilitar, reordenar, cambiar la coincidencia, el asignatario, el nivel o los otorgamientos. Reducir el nivel a observe es el interruptor de apagado de un clic de una regla. Requiere assistant:write; un token de agente es rechazado.

Eliminar una delegación permanente

Elimina la regla; los elementos que entregó vuelven al propietario, los recibos de lo que hizo el asignatario permanecen. Requiere assistant:write; un token de agente es rechazado.

Probar las delegaciones permanentes con hechos de muestra

Una ejecución de prueba: qué regla tomaría un asunto con estos hechos (buzón, clave, remitente, asunto, etiquetas, ocurrencias), y por qué. Nada cambia. Requiere assistant:write; un token de agente es rechazado.

Probar un efecto contra el nivel y los permisos de una delegación vigente

Una ejecución de prueba del orden de validación para un efecto solicitado bajo la regla hoy: el nivel permite el tipo; los permisos permiten los destinatarios, el volumen (el conteo de efectos ejecutados hoy), el horario, el gasto, las clases de riesgo leídas del asunto; el aprobador requerido aprobó. Responde el estado que tomaría un plan (proposed, approved, escalated o rejected) con cada verificación y por qué. Nada cambia. Requiere assistant:write; un token de agente es rechazado.

Leer las métricas de tareas

Los siete números de la capa de tareas en una ventana móvil (treinta días por defecto, window_days de 1 a 90), para la cuenta y para cada delegación permanente: asuntos cerrados sin el owner, el tiempo desde la llegada hasta done, los planes ejecutados como se propusieron, editados y rechazados, las escalations por asunto, las correcciones después de la ejecución, las collisions, el costo del modelo por asunto. Leído de los receipts, los planes, las escalations y el ledger; nada es estimado. Requiere assistant:read.

Listar la cola de aprobaciones

Los planes esperando al propietario (propuestos en borrador, o retenidos por un permiso) y las preguntas que los asignados hicieron, a través de los asuntos que el lector puede ver. Responder a través de las interacciones del elemento de trabajo: aprobar o rechazar un plan, elegir una opción o instruir sobre una pregunta. Requiere assistant:read. Un asunto creado a partir de un correo de autenticación antes de que ese correo quedara fuera del asistente se muestra con su título, su resumen, su petición y los efectos de su plan retenidos para un lector sin email:auth_secrets.

Enumerar las sugerencias de delegación

Las delegaciones permanentes que el asistente propone: un asunto que se repitió al menos tres veces en noventa días (la misma organización o remitente) y se manejó de la misma manera cada vez (ignored, answered, closed, handed to one agent), con la regla prellenada. Las abiertas por defecto. No se crea nada hasta que el propietario acepte. Requiere assistant:read; un token de agente es rechazado.

Aceptar o descartar una sugerencia de delegación

Aceptar: la sugerencia se cierra y la regla prellenada regresa para que el cliente la cree (POST /api/assistant/rules). Descartar: se cierra y nunca regresa para los mismos asuntos y manejo. Requiere assistant:write; un token de agente es rechazado.

Listar los permisos adjuntos a los asignatarios

Los permisos adjuntos a los agentes y miembros del propietario, además de cada regla que les entrega asuntos; se aplica el más estricto entre el de la regla y el del asignatario. Requiere assistant:read; un token de agente es rechazado.

Establecer los permisos de un asignatario

Adjuntar permisos a una identidad de agente o un miembro del espacio de trabajo; reemplazan los permisos anteriores del asignatario y limitan cada regla que les entrega asuntos. Requiere assistant:write; un token de agente es rechazado.

Eliminar los permisos de un asignatario

El asignatario conserva solo lo que cada regla otorga. Requiere assistant:write; un token de agente es rechazado.

Leer un sobre de tarea

El asunto entregado, como el asignado lo necesita: el resumen con la evidencia, los hechos, la delegación (asignado, regla, nivel, los tipos de efecto permitidos, los permisos efectivos), los planes abiertos y recientes, el arrendamiento. Un token de agent lee los asuntos entregados a él y los de los buzones que opera; el propietario lee los suyos. Requiere assistant:read. Un asunto creado a partir de un correo de autenticación antes de que ese correo quedara fuera del asistente se muestra con su título, su resumen, su petición y los efectos de su plan retenidos para un lector sin email:auth_secrets.

Tomar o renovar el arrendamiento en una tarea

Dos asignados nunca trabajan un asunto: el arrendamiento nombra quién lo trabaja hasta cuándo (quince minutos por defecto, hasta una hora). Tomarlo de nuevo lo renueva; otro titular es rechazado con TASK_LEASED hasta el vencimiento. Una solicitud de efectos toma el arrendamiento por sí misma. Requiere assistant:write.

Devolver el arrendamiento

Libera el arrendamiento que el llamador tiene; un arrendamiento en poder de otro asignado se deja solo. Requiere assistant:write.

Solicitar efectos en una tarea

El asignado solicita uno o más efectos (reply, forward, label, snooze, resolve, note, request). El nivel de la delegación decide los tipos permitidos y los permisos los limitan: dentro de los permisos en guarded_send u operate (y los tipos de entrada en triage) los efectos se ejecutan de inmediato con sus recibos; en draft esperan la aprobación del propietario; un permiso fallido escala al propietario; un tipo que el nivel no permite es rechazado. La propia solicitud del propietario se ejecuta de inmediato. La misma clave de idempotencia responde el primer plan de nuevo. Requiere assistant:write.

Detener y preguntar al propietario

El asignado hace una pregunta con la evidencia y, cuando es útil, las opciones que ve. El propietario responde con las interacciones ordinarias de elegir o instruir sobre la decisión que esto crea; el asunto se muestra en Today como que necesita al propietario, el arrendamiento se libera, la tarea espera. Requiere assistant:write.

Reportar sobre una tarea

Lo que hizo el asignado y cómo terminó: done (el asunto se resuelve, o espera cuando aún se espera una respuesta), blocked (se pregunta al propietario), o handed back (el propietario toma el control y la regla permanece fuera de este asunto). Las reclamaciones se concilian con los recibos que escribió la plataforma: una reclamación sin recibo se registra como una reclamación, nunca como un hecho. El arrendamiento se libera. Requiere assistant:write.

Lee lo que el asistente estableció sobre un mensaje

El conocimiento que los análisis de este mensaje produjeron: afirmaciones (sujeto, predicado, valor con tipo y moneda, base, confianza, validez, evidencia), entidades, compromisos y expectativas. Nada se calcula en el camino: un mensaje que el pipeline nunca analizó responde analysed: false con reason (not_enabled cuando el buzón no está en el asistente, not_analysed cuando el análisis aún no ha ocurrido). Requiere assistant:read.

Extrae los campos que necesitas de un mensaje con tu propio esquema

Una llamada al modelo sobre el texto del mensaje (asunto, remitente, cuerpo) con un esquema JSON del llamador de objetos y primitivos (hasta 8 KB, sin referencias): responde data en esa forma, confidence (0 a 1) y evidence_quotes (extractos textuales). Almacenado en caché por (mensaje, esquema, instrucciones) así que la misma pregunta cuesta una llamada (cached: true después). Limitado por el presupuesto de modelo de la cuenta (429 cuando se agota, 503 cuando la ruta del modelo está desactivada). Los correos de código de inicio de sesión responden 403 AUTH_MESSAGE. Los cuerpos de más de 60,000 caracteres responden 413.

Obtener configuración del asistente Mailzero

Devuelve el estado de activación del asistente, indicadores de sombra/pausa, versión de consentimiento, ruta de privacidad, alcance de buzones y todos los buzones que posees. Requiere el permiso 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"
    }
  ]
}

Actualizar configuración del asistente Mailzero

Habilita, pausa, reanuda o delimita explícitamente el procesamiento del asistente. Enviar mailbox_ids: [] deshabilita todos los buzones y cancela una importación de historial en curso. Reanudar requiere la versión de consentimiento actual. La recepción de correo permanece independiente. Requiere el permiso assistant:write.

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

Consentir e iniciar una importación de historial en segundo plano

Registra el consentimiento explícito actual de IA, habilita el procesamiento en segundo plano en los buzones seleccionados del usuario y crea una importación de historial reciente reanudable. El cliente puede cerrarse inmediatamente y consultar GET /api/assistant/backfill. Requiere el permiso 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"
  }
}

Obtener progreso de importación de historial en segundo plano

Devuelve la fase de escaneo/análisis, mensajes procesados y totales, porcentaje, ETA adaptativo, estado de pausa y si la aplicación puede cerrarse. Requiere el permiso 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
  }
}

Reintentar mensajes fallidos de importación de historial

Vuelve a encolar los fallos terminales de la importación más reciente para buzones que permanecen habilitados para IA. Los reintentos automáticos ya se han agotado antes de que un mensaje aparezca aquí. Requiere el permiso assistant:write.

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

Obtener la cola de decisiones fundamentadas de Today

Devuelve las proyecciones versionadas Now, Needs you, Waiting, Upcoming y Handled recientes con as_of, lag, coverage y warnings. Cada elemento enlaza a su mensaje de origen; nada aquí envía correo. Requiere el permiso assistant:read. El correo de autenticación (códigos de inicio de sesión, restablecimientos de contraseña, enlaces mágicos) nunca se convierte en un asunto y nunca llega a un modelo. Un asunto creado a partir de un correo de autenticación antes de que ese correo quedara fuera del asistente se muestra con su título, su resumen, su petición y los efectos de su plan retenidos para un lector sin 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": []
  }
}

Obtener un elemento Work del asistente y el plan actual exacto

Devuelve el elemento Work fundamentado, su Decision abierta y opciones, el plan Action actual exacto, compromisos y expectativas abiertas, interacciones y recibos. Requiere el permiso assistant:read. Un asunto creado a partir de un correo de autenticación antes de que ese correo quedara fuera del asistente se muestra con su título, su resumen, su petición y los efectos de su plan retenidos para un lector sin email:auth_secrets.

Leer el resumen de situación de un elemento de Trabajo

Un documento que un agente lee antes de actuar: la situación (estado, atención, recurrencia, remitente), la historia hasta ahora (cada correo de ella, analizado o no), los hechos que los análisis establecieron (afirmaciones con valor, base y validez, y las entidades), los compromisos y expectativas abiertas con qué se espera de quién y desde cuándo, lo que ya se resolvió (ciclos cerrados y recibos), la Decisión actual con sus opciones, un siguiente paso sugerido (la opción recomendada de la Decisión cuando hay una, de lo contrario una regla: una promesa vencida, una expectativa vencida para perseguir, la solicitud del remitente para responder), y los mensajes de evidencia. Determinista y económico: sin llamada al modelo. Los tokens de agente leen los elementos de los buzones que operan y los elementos que se les entregan.

Leer el resumen de situación para un corresponsal

Qué saber antes de responder a una persona: el resumen de su elemento de Trabajo activo más reciente en los buzones que puedes leer (o un buzón), los otros elementos que están pendientes, y sus últimos diez correos. brief es null cuando aún no se analizó nada de ellos.

Lee los hechos detrás de un elemento de Work

Las afirmaciones y entidades fusionadas de cada análisis del elemento (el más reciente gana primero), más sus compromisos y expectativas almacenados con su estado. Los tokens de agente leen los elementos de los buzones que operan y los elementos que se les entregan.

Marcar un elemento Work como abierto

Registra que el propietario abrió este elemento Work en su versión actual, lo que quita su marcador de no leído hasta que el elemento cambie de nuevo. Requiere el ámbito assistant:write.

Lo que el asistente aprendió sobre ti

Las reglas de silencio que el asistente propone después de que el mismo remitente u organización fue ignorado cada vez que volvió, los silencios vigentes (un remitente, un dominio o una situación que el asistente mantiene fuera de Hoy), cada uno con su motivo, y las etiquetas confirmadas una vez, cada una aplicada al próximo asunto del mismo proyecto sin preguntar. Acepta una regla de silencio mediante el endpoint suggestions; olvida un silencio con el endpoint mutes, una etiqueta con el endpoint tags.

Olvidar un silencio

El siguiente correo de ese remitente, dominio o situación vuelve a ser un ítem.

Olvidar una etiqueta

Ya no se aplica nada sin preguntar: el próximo asunto de ese proyecto propone la etiqueta de nuevo. Los asuntos que la llevan la conservan.

Investigar un asunto: lo que dicen el registro y los enlaces

Lee, en ese instante, los hechos que la infraestructura pública tiene sobre el dominio del remitente (su fecha de registro y registrador, su postura SPF y DMARC, si recibe correo), a dónde realmente va cada enlace del mensaje fuente (las redirecciones seguidas un salto a la vez, el host final y los hechos del dominio), y lo que cada adjunto realmente es (sus primeros bytes contra el nombre y el tipo declarado). Responde el dossier con las señales que los hechos agregan (un dominio registrado hace días, un enlace que aterriza en otro lugar, un dominio del remitente que no protege nada, un programa nombrado como un documento). Sin proveedor, sin cuenta, nada almacenado; una búsqueda que falla es un hecho en sí mismo.

Quién está detrás de un asunto: la organización, las personas involucradas, el historial

Responde la ficha del remitente de un asunto: la organización del remitente tal como la conoce el perfil de dominio almacenado (nombre, razón social, categoría, sitio web, fecha de registro, postura de correo; null para un dominio de correo compartido como gmail.com o un dominio nunca analizado, y nunca un análisis en vivo), las personas que los mensajes de la historia llevan en from, to y cc con sus roles y si pertenecen a la misma organización (los propios buzones del lector excluidos), y la relación: cuánto correo llegó desde esta dirección en los buzones del lector (contado hasta 50), cuándo por primera y última vez, los otros asuntos del remitente y los asuntos planteados por colegas del mismo dominio. Requiere el scope assistant:read.

Registrar una Decision humana delimitada

Elegir una opción, dar una instrucción, tomar el control, posponer, ignorar, corregir, reportar el veredicto de confianza (phishing o legítimo), o aprobar o rechazar un plan en espera (un plan aprobado se ejecuta de inmediato, con sus recibos en la respuesta). La llamada está delimitada por work_item_version y se repite de forma idempotente mediante idempotency_key. Elegir o instruir prepara un borrador exacto que aún pasa por el flujo de respuesta normal; este endpoint nunca envía correo. Requiere el scope assistant:write.

Obtener la vista previa exacta de la acción por ID opaco

Devuelve la identidad de respuesta exacta, destinatarios, cuerpo, compromisos y efectos secundarios de un plan de acción preparado, además de su vencimiento y revisión de origen, para que un cliente pueda mostrar qué sucederá antes de que el usuario envíe a través del endpoint de respuesta existente con assistant_plan_id. Requiere el scope assistant:read.

Obtener actividad del asistente con contenido minimizado

Lista las interacciones y recibos recientes atribuidos al llamador sin los cuerpos de los mensajes. Requiere el scope assistant:read.

Exportar datos derivados del asistente

Exporta análisis, reclamaciones aceptadas, decisiones, interacciones, recibos y uso del modelo como un adjunto JSON. Nunca incluye los cuerpos de correo electrónico de origen ni los bytes de adjuntos. Requiere el scope assistant:write. También requiere email:auth_secrets (de lo contrario, 403 INSUFFICIENT_SCOPE): el estado derivado puede contener lo que el asistente extrajo del correo de autenticación antes de que ese correo quedara excluido de él.

Eliminar datos derivados del asistente

Elimina de forma idempotente inteligencia derivada, trabajos, uso del modelo, dispositivos, importaciones y configuraciones mientras preserva el correo de origen. Requiere el permiso assistant:write.

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

Registrar un dispositivo para alertas Now anonimizadas

Registra o rota un token push cifrado para una instalación de aplicación y entorno. Solo la aplicación nativa llama a esto; requiere un asistente activo y el permiso assistant:write.

Revocar un registro de dispositivo

Revoca todos los registros push de una instalación, por ejemplo al cerrar sesión. Requiere el permiso assistant:write.

Verifique el estado del DNS del correo electrónico (MX, SPF, DMARC, DKIM)

Comprueba la configuración DNS del correo electrónico para un dominio: registros MX, SPF, DMARC y DKIM. Detecta automáticamente el proveedor de correo electrónico a partir de 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"

Obtenga un estado de entregabilidad de correo electrónico específico para el propietario

Separa la preparación determinista de autenticación, los resultados de entrega de 30 días ponderados por destinatario, el estado de seguridad de la cuenta y la ubicación medida por proveedor. La puntuación de preparación no es una probabilidad de bandeja de entrada; la ubicación no medida se devuelve como not_tested.

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

Configurar el correo electrónico en un dominio

Preconfigure el DNS de correo electrónico en un dominio (opcional). create_mailbox lo llama automáticamente cuando es necesario. Pase force=true para anular el proveedor de correo electrónico existente (Google Workspace, Fastmail, Proton).

Eliminar correo electrónico de un dominio

Elimine el correo electrónico de un dominio, elimine todos los buzones y mensajes y establezca emailEnabled en falso. Cambia el correo de todo el dominio, por lo que un token confinado a buzones recibe 403 MAILBOX_CONFINED.

Verificar el estado del DNS del correo electrónico

Verifique el estado de verificación de DNS del correo electrónico para un dominio. Devuelve si el dominio está verificado y listo, los detalles del registro DNS y el recuento de buzones.

Crear un buzón en domani.run

Cree una dirección de correo electrónico gratuita en domani.run (por ejemplo, hello@domani.run). No se requiere propiedad de dominio. Limitado a 1 buzón @domani.run gratuito por usuario. Muchas babosas comunes están reservadas.

Listar todos los buzones

Enumere todos los buzones de correo a los que puede acceder el identidad solicitante en todos los dominios, incluidas las concesiones de espacio de trabajo.

Crear un buzón

Cree una dirección de correo electrónico (buzón). Proporcione una dirección completa como "hello@mysite.com". El DNS del correo electrónico se configura automáticamente en el primer uso. Pase force=true para anular un proveedor de correo electrónico existente. La capacidad del buzón de correo de dominio personalizado está determinada por la cuenta activa o el plan de espacio de trabajo. Cada cuenta puede crear un buzón @domani.run gratuito por separado con POST /api/email. Pase workspace_id para crear el buzón dentro de un espacio de trabajo de su propiedad. Para un dominio personalizado, esto adopta explícita y atómicamente el dominio y todos sus buzones hermanos sin ámbito en ese espacio de trabajo; un dominio nunca se puede dividir en espacios de trabajo. Pase kind="hosted" para crear un buzón IMAP/SMTP real en su propio dominio (conecte Apple Mail, Thunderbird o cualquier cliente) en lugar del buzón API predeterminado (enviar/recibir a través de API + webhooks). Los buzones de correo alojados devuelven registros DNS para publicar, configuraciones del cliente de correo y una contraseña de aplicación única. Requiere un dominio de su propiedad.

Listar todos los buzones

Enumere todos los buzones de correo a los que puede acceder el identidad solicitante, incluidas las concesiones de espacio de trabajo. Igual que GET /api/email.

Obtener detalles del buzón

Obtenga detalles de un buzón de correo específico por su dirección de correo electrónico completa (codificada en URL, por ejemplo, hola%40misitio.com).

Actualizar buzón

Actualice el nombre para mostrar de un buzón, la URL del webhook o la dirección de correo electrónico de reenvío por su dirección de correo electrónico completa. Establezca en nulo para deshabilitar/borrar.

Eliminar un buzón

Eliminar un buzón por su dirección de correo electrónico completa. Requiere confirm=true en el cuerpo. Sin confirmación, devuelve una vista previa con message_count.

enviar un correo electrónico

Envía un correo desde un buzón identificado por su dirección completa. El servidor ejecuta primero una política versionada obligatoria: rechaza los fallos objetivos de seguridad y devuelve como advertencias los problemas de reputación y calidad del contenido. Para una respuesta colaborativa en un hilo, pasa el lease de composición, el reply_version observado y una clave de idempotencia estable; el servidor rechaza atómicamente las respuestas obsoletas o duplicadas justo antes del envío. Máximo 20 destinatarios únicos por mensaje. Límite: 100 destinatarios por hora y buzón.

Realice una verificación previa de un correo electrónico saliente

Ejecute la política del lado del servidor versionada exactamente utilizada por el punto final de envío sin enviar ni consumir cuota de correo electrónico. Se permiten enlaces de autenticación HTTPS públicos en dominios de terceros con una advertencia de reputación. Se bloquean las URL locales/privadas, los enlaces de autenticación que no sean HTTPS y los archivos adjuntos ejecutables; Los cuerpos de más de 102 KB producen una advertencia de recorte.

Listar correos electrónicos

Enumere los correos electrónicos en una carpeta canónica o vista virtual. El valor predeterminado es Bandeja de entrada. La ubicación de la carpeta es independiente de la dirección del mensaje y del veredicto de spam. El correo de autenticación (OTP/códigos de verificación, restablecimientos de contraseña y enlaces mágicos) se etiqueta como security: "auth". Los tokens sin el scope email:auth_secrets ven esos mensajes con el asunto y el cuerpo ocultos (redacted: true); los metadatos (remitente y fecha) siguen visibles. Los filtros subject, q y attachments coinciden con lo que quien llama puede leer: sin el alcance, ese mensaje solo coincide por su asunto y su cuerpo ocultos, así que una consulta por un código que contiene no encuentra nada.

Buscar correo por significado y por palabras

Busca en los buzones que puedes leer, o en un buzón con mailbox. Híbrido por defecto: el embedding del mensaje (pgvector, coseno) y el índice de palabras ponderadas se fusionan por rango recíproco con un pequeño impulso de recencia, en una sola sentencia; why indica qué rama coincidió. Operadores de Gmail en 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: para excluir, a OR b. Una consulta formada solo por operadores lista los mensajes coincidentes del más reciente al más antiguo (why: filter). Los códigos y enlaces de inicio de sesión, el spam y el correo del sistema nunca se indexan; los buzones listados en search_opt_out_mailbox_ids del asistente se buscan solo por palabras. Un token vinculado a una identidad de agente busca solo en los buzones que opera su agente. Requiere email:read. Sin email:auth_secrets, el correo de autenticación entrante se excluye antes de la clasificación: ninguna palabra, operador o filtro coincide con él, así que una búsqueda de un código de inicio de sesión no encuentra nada.

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

Comenzar a conectar una bandeja de entrada de Gmail

Devuelve la URL de consentimiento de Google vinculada a tu cuenta y al límite de importación. Ábrela en un navegador; después del consentimiento, la bandeja de entrada se convierte en un buzón conectado en su propia dirección, el correo recibido después del límite se importa (predeterminado: las últimas 24 horas), y el correo nuevo sigue a medida que llega. Nunca toda la bandeja de entrada: amplía más tarde con POST /api/emails/{address}/import. Requiere email:write. Google OAuth debe estar configurado en el servidor.

Comenzar a conectar una bandeja de entrada de Outlook

Devuelve la URL de consentimiento de Microsoft vinculada a tu cuenta y al límite de importación. Ábrela en un navegador; después del consentimiento, la bandeja de entrada se convierte en un buzón conectado en su propia dirección, se importa el correo recibido después del límite (predeterminado: las últimas 24 horas), y el correo nuevo sigue a medida que llega. Nunca la bandeja de entrada completa: amplía más tarde con POST /api/emails/{address}/import. Requiere email:write. Microsoft OAuth debe estar configurado en el servidor.

Lista las formas en que se puede conectar una bandeja de entrada

Una fila por proveedor (Gmail, Outlook, cualquier bandeja de entrada mediante reenvío, una dirección alojada aquí): cómo comienza la conexión (una pantalla de consentimiento, una regla de reenvío, una dirección creada), qué puede hacer la conexión (leer, o leer y escribir), si importa correo más antiguo, y si este servidor está configurado para ello. Muestra un botón de conectar solo cuando configured es true; reason nombra la variable faltante para el operador. Requiere email:read.

Conectar una bandeja de entrada mediante reenvío

Crea un buzón conectado en la propia dirección de la bandeja de entrada y responde con una dirección de reenvío en el dominio de reenvío de la plataforma, con los pasos para Gmail, Outlook y otros proveedores. Agrega una regla de reenvío en el proveedor; lo que llega a esa dirección se desenvuelve (remitente original, fecha, asunto) y se almacena bajo el buzón conectado. Gmail pide a la dirección de reenvío que confirme: el código y el enlace aparecen en la conexión. El primer correo que regresa, o una prueba (POST /api/emails/{address}/connector/verify), hace que la conexión esté activa. Solo el correo nuevo llega de esta manera; el correo antiguo no se puede importar. Requiere email:write. El dominio de reenvío debe estar configurado en el servidor.

Enviar una prueba a través de la regla de reenvío

Envía un correo a la bandeja de entrada conectada; cuando la regla de reenvío lo trae de vuelta a la dirección de reenvío, la conexión se vuelve activa. Solo para una conexión mediante reenvío. Requiere email:write.

Leer la conexión de un buzón conectado

Tipo, estado, el límite de importación, la fase de sincronización (el escaneo de importación, luego historial), el progreso de importación (escaneados, copiados, por analizar, analizados), la última sincronización y el último error. Requiere email:read. La confirmación de reenvío (el código y el enlace de Gmail) es correo de autenticación: sin email:auth_secrets, su código y su url son null y lleva redacted: true. Un token confinado a buzones solo encuentra sus propios buzones (404 en caso contrario).

Desconectar un buzón conectado

Elimina las copias propias de la persona (messages, attachments, filas de búsqueda, trabajos pendientes) y la credencial; mantiene la fila del buzón, el enlace marcado como desconectado, y lo que los agentes hicieron (receipts). Solo un buzón conectado puede ser desconectado. Requiere email:write.

Importar correo más antiguo de un buzón conectado

Amplía la importación a una fecha anterior: una nueva ejecución de importación copia el correo entre el nuevo límite y el actual, en orden de llegada, bajo su propio límite de costo. Se rechaza mientras un escaneo de importación aún está en ejecución. Requiere email:write.

Buscar en un buzón por significado y por palabras

La misma búsqueda que GET /api/emails/search, restringida a este buzón. Requiere email:read. Sin email:auth_secrets, el correo de autenticación entrante se excluye antes de la clasificación: ninguna palabra, operador o filtro coincide con él, así que una búsqueda de un código de inicio de sesión no encuentra nada.

Listar las conversaciones de un buzón

Mensajes agrupados de la forma en que los clientes de correo los agrupan: una respuesta se une al hilo del mensaje que responde (In-Reply-To, luego la cadena References), el correo sin encabezados utilizables se une al hilo más reciente con el mismo asunto y un corresponsal en común dentro de treinta días, todo lo demás inicia un hilo cuyo id es el id de su primer mensaje. Los hilos se ordenan por última actividad; la papelera y el spam nunca participan a menos que se nombren como la carpeta. folder=inbox|archive|sent mantiene los hilos que tienen un mensaje allí pero aún cuenta toda la conversación.

Leer una conversación, mensaje más antiguo primero

Cada mensaje del hilo (papelera incluida, para que no falte nada de la historia) con su texto, el más antiguo primero, más los participantes y el conteo de no leídos. El correo de autenticación se redacta de la forma en que se leen los mensajes.

Transmitir eventos del buzón (eventos enviados por el servidor)

Responde text/event-stream. Sin un cursor la transmisión comienza en el presente; con since (un cursor de /api/email/changes o el id de cualquier evento anterior) primero reproduce cada cambio después de ese punto, luego sigue el diario del buzón en vivo: cada frame lleva el tipo del cambio como el nombre del evento (message.received, message.updated, message.deleted, message.moved, message.status, mailbox.resync_required, assistant.item.delegated, assistant.item.recalled, ...), el cambio como datos JSON con su cursor reanudable, y ese mismo cursor como el id del frame. El primer frame es ready con el cursor desde el cual reanudar; un comentario de keep-alive llega cada 20 segundos; la conexión se cierra después de aproximadamente 5 minutos con un frame close y una sugerencia retry:. Reconecte con Last-Event-ID (o since) para reanudar sin brecha y sin duplicado. Los tokens de agente están confinados a los buzones que el agente opera. Una entrada sobre un elemento de trabajo creado a partir de un correo de autenticación lleva su title y su ask ocultos para un token sin email:auth_secrets.

Listar carpetas de correo electrónico y recuentos

Devuelva recuentos derivados del servidor para carpetas del sistema y vistas virtuales, además de capacidades de ciclo de vida para el backend del buzón.

Aplicar una acción de ciclo de vida a los mensajes.

Mueve, restaura, marca como leído, destaca o elimina permanentemente hasta 100 ID de mensajes explícitos. Pasar a la Papelera es reversible. La eliminación permanente requiere email:delete y solo acepta mensajes que ya están en la Papelera. Cada respuesta es un recibo de operación duradero con un resultado por identificación solicitada. Proporcione una clave estable en el encabezado estándar Idempotency-Key o en el campo JSON heredado idempotency_key y reutilícela después de los tiempos de espera; un reintento exacto devuelve el recibo almacenado sin otra mutación. Si se proporcionan ambos formularios, deben coincidir. Reutilizar una clave con una solicitud diferente devuelve 409. Cuando se omite, el servidor crea una clave y la devuelve en el cuerpo y en el encabezado Idempotency-Key. Devuelve 207 cuando solo una parte del lote tiene éxito.

Marcar mensajes como leídos o no leídos

Punto final de compatibilidad para actualizaciones de estado de lectura seguras para reintentos. Devuelve el recibo de operación canónico duradero por artículo más el recuento heredado. Proporcione y reutilice el encabezado Idempotency-Key o el campo de compatibilidad idempotency_key después de los tiempos de espera.

Eliminar mensajes en masa

Punto final de compatibilidad que mueve los mensajes a la Papelera con reintentos seguros. Devuelve el recibo de operación canónico duradero por artículo más el recuento heredado. Proporcione y reutilice el encabezado Idempotency-Key o el campo de compatibilidad idempotency_key después de los tiempos de espera.

Recibe un mensaje

Obtenga un único mensaje por ID de un buzón identificado por su dirección de correo electrónico completa. Los mensajes clasificados como correo de autenticación (OTP, restablecimiento de contraseña, enlace mágico) regresan con el asunto/cuerpo oculto a menos que el token tenga el alcance email:auth_secrets.

Eliminar un mensaje

Mueve un mensaje a la Papelera. Es reversible. Usa la acción de ciclo de vida delete_permanently y un token con email:delete para borrar un mensaje que ya esté en la Papelera.

Responder a un mensaje

Responde a un mensaje en un buzón identificado por su dirección completa. Los encabezados del hilo se completan automáticamente, y el original se cita debajo de la respuesta como hacen los clientes de correo (línea de atribución en el idioma de la cuenta, líneas > en el texto, un bloque gmail_quote en el HTML), salvo que quote sea false. Los clientes colaborativos deben pasar el lease de composición, el reply_version observado y una clave de idempotencia estable; el servidor rechaza atómicamente una respuesta obsoleta o duplicada justo antes del envío.

Reenviar un mensaje

Reenviar un mensaje desde un buzón identificado por su dirección de correo electrónico completa a otro destinatario. El reenvío de correo de autenticación (OTP, restablecimiento de contraseña, enlace mágico) requiere el alcance email:auth_secrets; exfiltraría el secreto.

Obtener información del avatar del buzón

Devuelve la URL de Gravatar (si está configurada) y el enlace de registro para un buzón identificado por su dirección de correo electrónico completa.

Obtener la configuración del webhook del buzón

Devuelve la URL del webhook, el secreto de firma, los nombres de los encabezados de autenticación configurados y el estado de un buzón. Los valores del encabezado nunca se devuelven.

Establecer webhook de buzón

Configure el destino HTTPS para los eventos de buzón firmados por HMAC: el correo entrante de forma predeterminada, más (opcional mediante events) el veredicto de entrega del correo enviado DESDE el buzón: un rebote llega al remitente segundos después de aceptarse el envío, en lugar de vivir solo en el historial del mensaje. Las entregas entrantes en vivo se almacenan de forma duradera, se intentan inmediatamente y se reintentan hasta tres veces. Cada intento incluye X-Domani-Delivery-Attempt a partir de 1. Los valores opcionales de autorización o X-API-Key se cifran y nunca se devuelven; los operadores humanos deben enviarlos fuera del contexto del modelo a través de las opciones de variables de entorno de la 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"]}'

Quitar webhook del buzón

Elimine la URL del webhook y el secreto de firma de un buzón. Sólo se almacenarán los correos electrónicos entrantes.

Rotar el secreto de firma del webhook

Vuelva a generar el secreto de firma HMAC-SHA256 para un webhook de buzón. El viejo secreto queda inmediatamente invalidado.

Probar el webhook del buzón

Envíe una carga útil de prueba firmada a la URL del webhook del buzón. Devuelve el estado HTTP y si la entrega se realizó correctamente. Las pruebas no se vuelven a intentar; las entregas entrantes en vivo se reintentan hasta tres veces.

Listar alias de buzones

Enumere todas las direcciones de alias que se entregan en un buzón. Los alias permiten que varias direcciones (ventas@, hola@, contacto@) compartan una bandeja de entrada sin utilizar una ranura de buzón.

Agregar un alias de buzón

Agregue una dirección de alias que entregue en este buzón, sin utilizar una ranura de buzón. El alias debe estar en el mismo dominio que el buzón. Proporcione un slug ("sales") o una dirección completa ("sales@mysite.com").

Eliminar un alias de buzón

Eliminar un alias de un buzón. El correo electrónico a esa dirección deja de entregarse.

Obtener la configuración del cliente de correo (alojado)

Obtenga la configuración de conexión IMAP/SMTP para un buzón alojado, para configurar Apple Mail, Thunderbird o cualquier cliente de correo. El nombre de usuario es la dirección completa; la contraseña es una contraseña de aplicación (cree una con POST /api/emails/{address}/credentials). Buzones de correo alojados únicamente.

Listar contraseñas de aplicaciones (alojadas)

Enumere las contraseñas de la aplicación para un buzón alojado. Los secretos se muestran sólo una vez en la creación; esto devuelve etiquetas y metadatos únicamente. Buzones de correo alojados únicamente.

Crear una contraseña de aplicación (alojada)

Cree una contraseña de aplicación para un buzón alojado, utilizada como contraseña en un cliente de correo (IMAP/SMTP). El secreto se devuelve una vez; guárdelo ahora. Buzones de correo alojados únicamente.

Revocar la contraseña de una aplicación (alojada)

Revocar la contraseña de una aplicación. Cualquier cliente de correo que lo utilice deja de conectarse inmediatamente. Buzones de correo alojados únicamente.

Marcar un mensaje para un humano

Escale un mensaje al humano de la cuenta (o borre la marca con clear=true). Establece needs_human en el mensaje, retiene su conversación en el estado needs_human y dispara el webhook email.escalated + una notificación dentro de la aplicación. La primitiva del producto detrás de 'answer the easy ones, stop on the one the human must decide' (responder las fáciles y detenerse en la que debe decidir el humano).

Establecer un recordatorio de seguimiento

Establezca (o borre con clear=true) un recordatorio de seguimiento de un solo uso en un mensaje. Cuando llega remind_at y el mensaje sigue sin respuesta (entrante: no se envió respuesta; saliente: no se recibió respuesta entrante), email.reminder_due se dispara como webhook + notificación dentro de la aplicación y el recordatorio se borra solo.

Listar contactos

La libreta de direcciones de la cuenta, alimentada automáticamente por el tráfico de correo: corresponsales, recuentos de mensajes, última actividad y notas. Por defecto, los más recientemente activos primero (order=recent), para mostrar: un contacto que recibe correo nuevo durante un recorrido paginado pasa por delante del cursor, así que ese recorrido puede omitirlo. Para sincronizar la libreta completa, pase order=created: los más antiguos primero por fecha de creación y luego por id, una clave que nunca cambia, así que cada contacto que existe durante todo el recorrido se devuelve exactamente una vez y los contactos creados mientras tanto llegan al final. Un cursor solo continúa el orden del que proviene (400 INVALID_CURSOR en caso contrario). Agrega datos de todos los buzones, por lo que los tokens confinados a un buzón se rechazan (400 MAILBOX_CONFINED).

Crear o actualizar un contacto

Guarde un contacto: establezca un nombre para mostrar y adjunte notas ('prefers short emails', 'decision maker at Acme'). El tráfico de correo sigue alimentando los recuentos de mensajes de todos modos.

Eliminar un contacto

Elimine un contacto de la libreta de direcciones. El tráfico de correo lo volverá a crear como contacto automático si vuelve a escribir.

Listar reglas de correo entrante

Enumere las reglas de filtrado entrante de un buzón, en el orden de prioridad en que se aplican (la primera coincidencia gana).

Agregar una regla de correo entrante

Añade una regla para mensajes entrantes que coincidan con un campo (from/to/subject/body). Acciones: drop, mark_read, forward (action_arg = dirección), webhook_only (omite el reenvío) y label (action_arg = etiqueta). Las reglas se aplican por prioridad ascendente; gana la primera coincidencia.

Eliminar una regla de correo entrante

Eliminar una regla de filtrado entrante de un buzón.

Establecer dominio general

Enrute cada correo electrónico enviado a una dirección no coincidente en el dominio a un buzón designado. Todo lo que no coincida con un buzón, una subdirección o un alias se incluye en el cuadro general. El buzón ya debe existir en el dominio. Cambia el correo de todo el dominio, por lo que un token confinado a buzones recibe 403 MAILBOX_CONFINED.

Borrar dominio general

Elimine el comodín en un dominio. El correo electrónico a direcciones no coincidentes se eliminará nuevamente. Cambia el correo de todo el dominio, por lo que un token confinado a buzones recibe 403 MAILBOX_CONFINED.

Sincronizar incrementalmente un buzón

Llame sin cursor para capturar una línea de base antes de una instantánea completa limitada. Luego pase next_cursor para reproducir las mutaciones que ocurrieron durante y después de esa instantánea. Los cursores son opacos, están firmados, están vinculados al buzón y caducan después de 30 días. Las notificaciones automáticas son sólo sugerencias de invalidación; este diario es la fuente de recuperación duradera. Una entrada sobre un elemento de trabajo creado a partir de un correo de autenticación lleva su title y su ask ocultos para un token sin email:auth_secrets.

Listar direcciones suprimidas

Incluya direcciones en su lista de supresión: rebotes permanentes y quejas (ingeridas automáticamente a partir de eventos de entrega) además de entradas manuales. Los envíos a estas direcciones se omiten. Paginado por cursor.

Agregar una supresión

Agregue manualmente una dirección a su lista de supresión para que los envíos futuros la omitan. Los rebotes duros y las quejas se agregan automáticamente; Úselo para las direcciones a las que desea dejar de enviar correos electrónicos. Idempotente.

Eliminar una supresión

Elimine una dirección de su lista de supresión para poder enviarla por correo electrónico nuevamente (por ejemplo, después de que el destinatario arregló su buzón).

Solicitar una transferencia de propiedad del espacio de trabajo

Sólo propietario. Envía un enlace de aceptación de 48 horas a un miembro existente. Nada se mueve hasta que ese miembro autenticado acepte.

Revocar una transferencia de propiedad pendiente

Aceptar la propiedad del espacio de trabajo

Sólo objetivo. Transfiere atómicamente el espacio de trabajo, los dominios de ámbito y los buzones de correo; el propietario anterior se convierte en administrador y el pagador existente permanece sin cambios.

Crea una nueva cuenta

Empieza a crear una cuenta nueva (o inicia sesión en una existente) enviando un enlace de inicio de sesión por correo; aquí no se devuelve ninguna clave de API. Una persona que haga clic en ese enlace desde un navegador llega al panel ya con la sesión iniciada. Una CLI o un agente sin sesión de navegador debe usar en su lugar el flujo de inicio de sesión por dispositivo (POST /api/auth/cli y luego sondear GET /api/auth/cli/poll), que envía por correo la misma aprobación y devuelve una clave de API una vez aprobada - la respuesta lo indica en next_steps. Pasar un código ref vincula de forma permanente al nuevo usuario con un referente - el referente gana una comisión sobre todas las futuras compras de dominios de este usuario.

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

Enviar un correo electrónico de inicio de sesión con enlace mágico

Envía un enlace de inicio de sesión al correo electrónico proporcionado. Si el usuario no existe, primero crea una cuenta. El enlace mágico redirige al panel con credenciales de autenticación. Para acceso API programático, use POST /api/auth/register para obtener una clave API directamente.

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

Verificar un token de enlace mágico

Valida el token de enlace mágico y lo redirige al panel con credenciales de autenticación. Utilizado por el correo electrónico de enlace mágico; normalmente los agentes no lo llaman directamente. Los agentes deberían usar POST /api/auth/register en su lugar.

Generar un código de inicio de sesión de un solo uso entre hosts

Solo para el navegador: permite que una persona con sesión iniciada en domani.run o mailzero.run retome su sesión en el otro host sin un segundo enlace mágico. Devuelve una URL cuyo fragmento lleva un código de un solo uso, válido 60 segundos y vinculado al host; el código nunca se registra ni se envía en una cadena de consulta. No sirve fuera de una sesión de navegador, por lo que no se expone como herramienta de agente.

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

Canjear un código de inicio de sesión de un solo uso entre hosts

Solo para el navegador: lo llama la página /auth/handoff en el host de destino para canjear el código del fragmento de la URL por una sesión, exactamente como hace GET /api/auth/verify con un enlace mágico. El código debe coincidir con el Host al que llegó esta solicitud. No es una herramienta de agente.

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

Obtener detalles de la cuenta actual

Devuelve la información de la cuenta del usuario autenticado, incluido el correo electrónico, el estado del pago, el estado de la información de contacto, el código de referencia y el recuento de uso. Los agentes deben llamar a esto después de la autenticación para verificar has_payment_method y has_contact antes de intentar realizar 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"

Actualizar preferencias de cuenta

Actualice el método de pago preferido del usuario autenticado y/o la configuración regional de BCP 47. Las respuestas de la API permanecen estructuradas y no se traducen.

Eliminar cuenta (bloqueada mientras se mantienen los dominios)

Elimine permanentemente la cuenta, los tokens, los webhooks, los buzones de correo y otros datos de la aplicación del usuario autenticado. Los dominios registrados NO se eliminan con la cuenta: la solicitud falla con 409 HAS_DOMAINS hasta que se transfieren todos los dominios. Esta acción no se puede deshacer.

Obtenga un estado de activación veraz y las siguientes acciones recomendadas

Devuelve hitos del producto derivados del servidor y acciones siguientes teniendo en cuenta la capacidad. Se excluyen deliberadamente la creación y el uso de tokens, las visitas a páginas y el estado de la lista de verificación del cliente.

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

Descartar o restaurar la guía de primera ejecución

Almacena únicamente la preferencia de presentación. No puede completar un hito del producto.

Obtener información de contacto del registrante

Devuelve la información de contacto WHOIS del titular del usuario autenticado. Opcional para compras (mientras no esté configurada, el contacto de Domani mantiene los nuevos dominios en nombre del usuario), obligatoria para una transferencia entrante.

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

Establecer información de contacto del registrante

Configura o actualiza tu información de contacto WHOIS del titular. Opcional para compras, obligatoria para una transferencia entrante. Se convierte en el contacto titular y de facturación de tus dominios: mientras no esté configurada, el contacto de Domani los mantiene en tu nombre. Al actualizarla, el nuevo contacto se envía a todos tus dominios activos en los registradores que admiten cambios de contacto, lo que te convierte en su titular; el registrador puede pedirte por correo que lo confirmes en un plazo de 15 días.

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 verificación de correo electrónico de contacto

Vuelva a enviar el correo de verificación a la dirección de contacto de la cuenta. Limitado a un envío cada 15 minutos por dirección.

Listar los dispositivos conectados

Cada navegador, app móvil y terminal con la sesión iniciada en la cuenta, primero la sesión de quien llama (current). Cada inicio de sesión abre su propia sesión, así que iniciar sesión en un dispositivo nuevo nunca cierra la de otro. La ubicación es desde donde inició sesión el dispositivo (país y ciudad según su IP), ausente si se desconoce. Las claves de API no son sesiones: lístalas 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"

Cerrar la sesión en todos los demás dispositivos

Cierra todas las sesiones de la cuenta excepto la que hace la solicitud. Esos dispositivos deberán iniciar sesión de nuevo en su próxima solicitud. Las claves de API no cambian.

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

Cerrar la sesión de un dispositivo

Cierra una sesión. current designa la sesión que hace la solicitud (cerrar la propia sesión no requiere alcance); cualquier otra sesión requiere 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 los tokens de API de una identidad de agente

Los tokens vinculados a esta identidad de agente (claves enmascaradas, scopes, confinamiento de buzones, último uso). Un token vinculado a un agente es la vista de ese agente sobre cada superficie de asistente y correo.

Dar a un agente su propia clave de API en una sola llamada

Crea un token vinculado a esta identidad de agente, confinado a los buzones que el agente opera, con los scopes mínimos que un agente necesita (assistant:read, assistant:write, email:read, email:write). Con esa clave el agente lee solo su propio Today, sus buzones y los elementos que se le entregan; nombrar otro agente responde 403 y las rutas exclusivas del propietario (settings, backfill, export) lo rechazan. La clave completa se devuelve solo en esta respuesta. Requiere tokens:write. Un agente que no opera ningún buzón no recibe alcances de correo por defecto, y pedirlos responde 400 AGENT_MAILBOXES_REQUIRED: una clave sin buzones alcanzaría todos los buzones de la cuenta.

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

Revocar un token de API de un agente

Revoca un token vinculado a esta identidad de agente. Deja de funcionar inmediatamente. Requiere tokens:write.

Enumere sus tokens API

Devuelve todos los tokens de API para el usuario autenticado. Las claves están enmascaradas por seguridad (los primeros 12 + últimos 4 caracteres son visibles). Utilice esto para auditar tokens activos.

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

Crear un nuevo token API

Crea un nuevo token de API. La clave completa se devuelve solo en esta respuesta; guárdela de forma segura. Puede crear varios tokens para separar el acceso a diferentes aplicaciones.

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

Revocar un token de API

Revoca permanentemente un token API. Cualquier aplicación que utilice este token perderá el acceso inmediatamente. Esta acción no se puede deshacer.

{
  "success": true
}

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

Listar eventos de auditoría de seguridad

Devuelve el registro de auditoría de seguridad de la cuenta, del más reciente al más antiguo: ciclo de vida del token (creación, revocación, intentos de escalada), denegaciones por límite de gasto y max_price, cargos, solicitudes de pago y eliminaciones de cuenta bloqueadas. Úsalo para supervisar la actividad de los tokens de tus agentes.

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

Enumere todos los puntos finales de webhook configurados para su cuenta. Devuelve la URL, los eventos suscritos y el estado activo de cada webhook. Los secretos nunca se devuelven después de la creación. Un token confinado a buzones solo ve los webhooks confinados a sus propios buzones.

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

Crear webhook

Registre un nuevo punto final de webhook HTTPS. Los valores de autorización opcional o clave X-API se cifran en reposo y se incluyen en cada entrega. El secreto de firma se devuelve sólo una vez. Máximo 5 webhooks por cuenta. Un webhook creado por un token confinado a buzones queda confinado a los mismos buzones: no recibe ningún evento de correo de otro buzón.

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

Actualizar webhook

Actualice la URL de un webhook, los eventos suscritos, el estado activo o los encabezados de autenticación cifrados. Envíe sólo los campos que desee cambiar. Un token confinado a buzones solo alcanza los webhooks confinados a sus propios buzones (404 en caso contrario).

Eliminar webhook

Eliminar un punto final de webhook. Todas las entregas pendientes serán canceladas. Esto no se puede deshacer. Un token confinado a buzones solo alcanza los webhooks confinados a sus propios buzones (404 en caso contrario).

Listar entregas de webhooks

Obtenga intentos de entrega recientes para un webhook. Muestra el tipo de evento, el estado de HTTP, el número de intentos y cualquier error. Útil para depurar entregas fallidas. Un token confinado a buzones solo alcanza los webhooks confinados a sus propios buzones (404 en caso contrario).

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

Reproducir una entrega de webhook

Clona y vuelve a entregar inmediatamente un evento de webhook inmutable. La carga útil del evento y el ID del evento permanecen idénticos; la firma HMAC recibe una nueva marca de tiempo. Una clave de idempotencia requerida garantiza que los reintentos de la persona que llama nunca se envíen dos veces. Un token confinado a buzones solo alcanza los webhooks confinados a sus propios buzones (404 en caso contrario). Una excepción a la carga útil idéntica: un asunto copiado de un correo de autenticación se envía oculto, ya que la URL del webhook puede haber cambiado desde el primer envío.

Listar tipos de eventos de webhook

Enumere todos los tipos de eventos de webhook disponibles con descripciones. No se requiere autenticación.

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

Lista de notificaciones

Enumere sus notificaciones dentro de la aplicación con paginación basada en cursor. Incluye eventos de transacciones, actualizaciones de listados y alertas del sistema. Requiere alcance notifications:read. Una notificación escrita antes de que los asuntos de correo se ocultaran al escribirse se lee con el asunto del correo de autenticación oculto, en body y data.subject, para un token sin email:auth_secrets.

Obtener recuento de notificaciones no leídas

Punto final ligero para sondear el recuento de notificaciones no leídas. Requiere alcance notifications:read.

{
  "unread_count": 3
}

Marcar notificación como leída

Marcar una sola notificación como leída. Requiere alcance notifications:read.

Marcar todas las notificaciones como leídas

Marcar todas las notificaciones no leídas como leídas. Requiere alcance notifications:read.

Obtener preferencias de notificación

Devuelve las preferencias de notificación del usuario para cada categoría y canal (in_app, email). Las preferencias que faltan están habilitadas de forma predeterminada. Requiere alcance notifications:read.

Actualizar preferencias de notificación

Actualice las preferencias de notificación para categorías y canales específicos. Requiere alcance notifications:read.