API v1 JSON Autenticación por token REST

Referencia de la API

Cree integraciones para Skysnag con tokens de API con permisos limitados. Autentíquese con X-Api-Token Encabezado — no es autenticación Bearer. Todas las respuestas son JSON con formatos de error predecibles.

Iniciar sesión Inicio rápido Colección de Postman Archivo de entorno
https://developers.skysnag.com/api/v1
X-Api-Token
sk_snag_…
60 solicitudes/min

Inicio rápido

Tres pasos para su primera solicitud autenticada.

  1. Solicitar acceso a la API — Enviar desde Solicitudes de acceso a la API. Un administrador habilita el acceso a la API en su cuenta.
  2. Crear un token con alcance — Abra Tokens de API, seleccione los alcances y copie el token completo de inmediato (se muestra solo una vez).
  3. Enviar solicitudes autenticadas — Incluir X-Api-Token: sk_snag_… en cada llamada protegida.
cURL — comprobación de estado (sin autenticación) 
curl -s "https://developers.skysnag.com/api/v1/health" \
  -H "Accept: application/json"

Colección de Postman

Importe una colección y un entorno listos para explorar todos los endpoints v1 en Postman.

  1. Descargar la colección — Skysnag-API-v1.postman_collection.json
  2. Descargar el entorno — Skysnag-API-v1.postman_environment.json (completado previamente con la URL base de esta aplicación: https://developers.skysnag.com/api/v1)
  3. Importar ambos archivos en Postman → Importar → arrastra los archivos JSON o búscalos.
  4. Configure su token — En el entorno, establezca api_token con su token completo de Tokens de API.
  5. Ejecutar solicitudes — Comience con System → Health, luego Authentication → Get Me.
Descargar colección Descargar entorno

Autenticación

Protected endpoints require a personal API token in a dedicated header. Do not use Authorization: Bearer.

EncabezadoValorCuando
X-Api-Token Full token (sk_snag_…) Todos los endpoints protegidos
cURL — solicitud autenticada 
curl -s "https://developers.skysnag.com/api/v1/auth/me" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here"
Pruebe la API en su navegador

Pegue un token para habilitar la consola Pruébalo en los endpoints Obtener a continuación (solo lectura). Las solicitudes se ejecutan contra su cuenta en producción en https://developers.skysnag.com/api/v1. El token se guarda solo en este navegador (localStorage) y nunca se envía a ningún otro lugar excepto a esta API.

Clave no establecida

URL base y encabezados

Todas las rutas v1 son relativas a la URL base indicada a continuación.

https://developers.skysnag.com/api/v1
https://api.skysnag.com/v1
EncabezadoValorNotas
Aceptarapplication/jsonSiempre
Tipo de contenidoapplication/jsonal enviar un cuerpo
X-Api-TokenSu token de APIPuntos finales protegidos
X-Request-IdUUID (opcional)Correlacionar registros; reflejado en errores

Respuestas

Success payloads are wrapped in a data envelope.

JSON — envoltorio de éxito 
{
  "data": { ... }
}
JSON — GET /health 
{
  "data": {
    "status": "ok",
    "version": "v1"
  }
}

Errores

Errors return a stable code, human message, and request_id for support.

JSON — envoltura de error 
{
  "error": {
    "code": "missing_api_token",
    "message": "API token is required...",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
HTTPCódigoDescripción
401Falta el token de la APIX-Api-Token no proporcionado
401Token de API no válidoToken desconocido, revocado o caducado.
403Acceso a la API deshabilitadoLa cuenta no tiene acceso a la API
403Plan de API no elegiblePlan Comply o de prueba — actualizar a Protect o Suite
403Permisos insuficientesEl token no tiene el ámbito requerido
422Error de validaciónCuerpo de la solicitud no válido
404No encontradoRecurso no encontrado
429Error HTTPLímite de solicitudes excedido
500Error internoError de servidor inesperado

Paginación de la lista

List endpoints return pagination metadata alongside data.

ParámetroTipoPredeterminadoDescripción
páginaEntero1Número de página (comienza en 1)
límiteEnterovaríaElementos por página (máx. 100)
JSON — respuesta paginada 
{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 120,
    "has_more": true
  }
}

Límites de tasa

Each token is limited to 60 requests per minute by default.

Si se supera el límite, la API devuelve HTTP 429. Implemente un backoff exponencial. Póngase en contacto con el soporte para obtener límites más altos.

Permisos

Los tokens reciben permisos con alcance. Los endpoints rechazan las solicitudes cuando falta el alcance requerido.

API v1 scopes

AlcanceDescripción
account:readRead account and token metadata
me:readRead current user profile, permissions, domains, and security
me:writeUpdate current user profile
users:readList account users and domain access
users:writeCreate, update, and delete account users
tokens:readList active API tokens
tokens:writeCreate and revoke API tokens
domains:readList and read domains
domains:writeCreate, update, and delete domains

Legacy scopes

Válido para tokens existentes de integraciones antiguas. No es necesario para los nuevos endpoints de autenticación v1.

AlcanceDescripción
email-trust:readRead DMARC/SPF/BIMI trust data
reports:readRead aggregate and compliance reports
integrations:readRead integration settings
integrations:writeManage integrations

Referencia de la API

Documentación de los endpoints para la superficie v1 actual.

Revisión de salud

GET /health

Comprobación pública del estado. No se requiere autenticación.

CampoTipoDescripción
data.statusstringok cuando esté alcanzable
data.versionstringVersión de la API (v1)
HTTP 
curl -s "https://developers.skysnag.com/api/v1/health" \
  -H "Accept: application/json"
GET /auth/scopes

Devuelve los scopes asignables agrupados por v1 y legacy. No se requiere autenticación.

cURL 
curl -s "https://developers.skysnag.com/api/v1/auth/scopes" \
  -H "Accept: application/json"
JSON — respuesta 
{
  "data": {
    "v1": [{"id": "account:read", "description": "...", "group": "v1"}],
    "legacy": [{"id": "domains:read", "description": "...", "group": "legacy"}]
  }
}
GET /auth/me account:read

Devuelve la cuenta autenticada y los metadatos del token utilizado. Alias de GET /account.

cURL 
curl -s "https://developers.skysnag.com/api/v1/auth/me" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here"

API del usuario actual

Leer y actualizar el usuario autenticado. Esquemas: users, roles, teams, user_regions, domain_accesses, webauthn_credentials, password_securities.

GET /me me:read

Perfil de usuario actual.

cURL 
curl -s "https://developers.skysnag.com/api/v1/me" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here"
GET /me/permissions me:read

Permisos efectivos derivados del rol de usuario y de la configuración de la cuenta.

cURL 
curl -s "https://developers.skysnag.com/api/v1/me/permissions" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here"
GET /me/domains me:read

Dominios visibles para el usuario actual. Admite page y limit.

cURL 
curl -s "https://developers.skysnag.com/api/v1/me/domains?page=1&limit=25" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here"
GET /me/security me:read

Estado de seguridad de la autenticación multifactor (MFA) y de la passkey del usuario actual.

cURL 
curl -s "https://developers.skysnag.com/api/v1/me/security" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here"
PATCH /me me:write

Actualice el perfil de usuario actual.

CampoTipoDescripción
NombrestringNombre para mostrar (máx. 50 caracteres)
IdiomastringCódigo de idioma preferido
cURL 
curl -s "https://developers.skysnag.com/api/v1/me" \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here" \
  -d '{
    "name": "Updated Name"
  }'

API de gestión de usuarios

Gestionar los miembros del equipo de la cuenta. Requiere que la cuenta autenticada sea la propietaria del equipo. Esquemas: users, roles, teams, domain_accesses, password_securities, webauthn_credentials, user_detail_changes_history.

GET /roles users:read

Enumera los roles que se pueden asignar al invitar o actualizar a miembros del equipo. Propietario, Administrador y Editor están excluidos.

GET /roles/{role_id} users:read

Obtener detalles de un solo rol asignable.

GET /users users:read

Listar usuarios de la cuenta en el equipo actual.

POST /users users:write

Crear una invitación para un miembro de la cuenta. De forma predeterminada se envía un correo electrónico de invitación.

GET /users/{user_id} users:read

Obtener detalles del usuario.

PATCH /users/{user_id} users:write

Actualizar datos del usuario.

DELETE /users/{user_id} users:write

Eliminar a un miembro del equipo.

PATCH /users/{user_id}/status users:write

Alternar el estado del usuario. Cuerpo: {"enabled": true}

PATCH /users/{user_id}/role users:write

Cambiar rol. Cuerpo: {"role_id": 5}

PATCH /users/{user_id}/enforce-2fa users:write

Alternar la aplicación de la autenticación de dos factores (2FA). Cuerpo: {"enabled": true}

POST /users/{user_id}/reinvite-user users:write

Reenviar el correo electrónico de invitación de la cuenta a un miembro del equipo existente.

GET /users/{user_id}/domains users:read

Listar accesos a dominios de un usuario.

API de gestión de dominios

Administrar dominios de la cuenta. Las operaciones de escritura requieren la cuenta del propietario del equipo. Esquemas: domains, domain_groups, domain_accesses, domain_states, domain_snapshot, parked_domains, license_domain, domains_services, cloudflare_records.

GET /domains domains:read

Enumera los dominios visibles para la cuenta. Admite page y limit.

POST /domains domains:write

Crear un dominio. Cuerpo: {"fqdn": "example.com", "parent_domain_id": null}

POST /domains/bulk domains:write

Añadir dominios en bloque. Cuerpo: {"domains": ["example.com", "example.org"]}. Devuelve un ID de trabajo.

GET /domains/bulk/{job_id} domains:read

Obtener el estado del trabajo de adición masiva y los resultados por dominio.

GET /domains/{domain_id} domains:read

Obtener detalles del dominio, incluidos DNS y estado de verificación.

PATCH /domains/{domain_id} domains:write

Editar metadatos del dominio (grupo, estado, estado de incorporación, dominio padre)

DELETE /domains/{domain_id} domains:write

Eliminar un dominio y los registros alojados relacionados.

POST /domains/{domain_id}/verify domains:write

Verificar los registros DNS del dominio. Campos opcionales del cuerpo: dmarc_record, spf_record, bimi_record, tls_rpt_record, mta_sts_record.

POST /domains/{domain_id}/check-dns domains:write

Realizar una consulta/comprobación DNS y almacenar el resultado para su recuperación.

GET /domains/{domain_id}/dns-fetch-result domains:read

Obtiene el último resultado de obtención de DNS almacenado por check-dns (caché durante 7 días). El cuerpo de la respuesta de check-dns ya incluye el resultado completo; use este endpoint para recuperarlo más tarde sin volver a ejecutar la comprobación.

GET /domains/{domain_id}/status domains:read

Obtener estado de verificación de protocolos (DMARC, SPF, MTA-STS, TLS-RPT, BIMI).

GET /domains/{domain_id}/services domains:read

Obtener servicios adjuntos de envío de correo electrónico.

PATCH /domains/{domain_id}/services domains:write

Reemplazar servicios adjuntos. Cuerpo: {"service_ids": [1, 2]}

API de grupos de dominios

Organizar dominios en grupos. Los grupos son propiedad del equipo de la cuenta; se requiere un propietario del equipo para las operaciones de escritura.

GET /domain-groups domains:read

Listar grupos de dominios de la cuenta con el número de dominios.

POST /domain-groups domains:write

Crear un grupo de dominios. Cuerpo: {"name": "Production", "status": "active"} (status opcional).

GET /domain-groups/{group_id} domains:read

Obtener un único grupo de dominios.

PATCH /domain-groups/{group_id} domains:write

Editar un grupo de dominios. Cuerpo: {"name": "New name", "status": "active"} (ambos opcionales).

DELETE /domain-groups/{group_id} domains:write

Eliminar un grupo de dominios. Los dominios miembros se desagrupan, no se eliminan.

GET /domain-groups/{group_id}/domains domains:read

Listar dominios en un grupo (paginado)

POST /domain-groups/{group_id}/domains domains:write

Agregar un dominio al grupo. Cuerpo: {"domain_id": 123}.

DELETE /domain-groups/{group_id}/domains/{domain_id} domains:write

Eliminar un dominio del grupo (el dominio dejará de estar agrupado)

API DMARC alojada

Administre los registros DNS DMARC alojados por Skysnag, la política de aplicación, el historial y las recomendaciones para un dominio. Se requiere ser propietario del equipo para realizar operaciones de escritura.

GET /domains/{domain_id}/hosted-dmarc domains:read

Devuelve el nombre del registro alojado, el valor, el estado de habilitación y la política actual.

POST /domains/{domain_id}/hosted-dmarc domains:write

Provisionar el registro TXT DMARC alojado por Skysnag para el dominio.

PATCH /domains/{domain_id}/hosted-dmarc domains:write

Actualizar etiquetas DMARC avanzadas: p, sp, pct, adkim, aspf, rua, ruf, etc.

DELETE /domains/{domain_id}/hosted-dmarc domains:write

Eliminar el registro DMARC alojado del DNS de Skysnag.

GET /domains/{domain_id}/dmarc-policy domains:read

Lea la política DMARC efectiva y los ajustes de etiquetas analizados.

PATCH /domains/{domain_id}/dmarc-policy domains:write

Actualizar solo la aplicación de la política. Cuerpo: {"policy": "quarantine"} o {"p": "reject"}

GET /domains/{domain_id}/dmarc/history domains:read

Registros de actividad y capturas instantáneas de DMARC. Admite page y limit.

POST /domains/{domain_id}/dmarc/recommendation domains:read

Nivel de aplicación sugerido basado en las estadísticas de alineación y el período de supervisión.

API de SPF alojada

Gestionar registros SPF alojados en Skysnag, inclusiones (include), acciones de autorización de IP y flattening para un dominio. Se requiere ser propietario del equipo para operaciones de escritura.

GET /domains/{domain_id}/hosted-spf domains:read

Devuelve el nombre/valor del registro SPF alojado, el registro que debe publicarse en su dominio, el estado de habilitación, el calificador terminal all y el número de consultas.

POST /domains/{domain_id}/hosted-spf domains:write

Configure el registro SPF alojado por Skysnag para el dominio.

PATCH /domains/{domain_id}/hosted-spf domains:write

Editar configuración avanzada de SPF. Cuerpo: {"all": "~all"} (una de las opciones -all, ~all, ?all, +all).

DELETE /domains/{domain_id}/hosted-spf domains:write

Desactive el SPF alojado y elimine el registro del DNS de Skysnag.

GET /domains/{domain_id}/spf/history domains:read

Registros de actividad SPF y capturas instantáneas de registros. Admite page y limit.

GET /domains/{domain_id}/spf/includes domains:read

Listar los includes de SPF configurados para el dominio.

POST /domains/{domain_id}/spf/includes domains:write

Agregar un include de SPF. Cuerpo: {"include_content": "_spf.google.com"}

DELETE /domains/{domain_id}/spf/includes/{include_id} domains:write

Eliminar un include SPF del registro alojado.

GET /domains/{domain_id}/spf/ip-actions domains:read

Lista de acciones de autorización de IP SPF (Permitir / Rechazar).

POST /domains/{domain_id}/spf/ip-actions domains:write

Autorizar o bloquear una IP. Body: {"ip": "203.0.113.10", "type": "Allow"} (type = Allow o Reject).

POST /domains/{domain_id}/spf/flatten domains:read

Genera un registro SPF aplanado resolviendo los includes en rangos de IP. Devuelve el registro aplanado, las listas IPv4/IPv6 y el recuento de consultas DNS frente al límite.

API de BIMI / VMC

Administrar registros BIMI, logotipos SVG, certificados VMC y comprobaciones de preparación. Se requiere el propietario del equipo para las operaciones de escritura.

GET /bimi/registrations account:read

Listar solicitudes de registro BIMI de socios para el equipo de cuentas.

GET /domains/{domain_id}/bimi domains:read

Devuelve detalles del registro BIMI, destinos DNS, estado del logo/VMC y resultados de la inspección SVG.

POST /domains/{domain_id}/bimi domains:write

Provisionar BIMI alojado para el dominio.

PATCH /domains/{domain_id}/bimi domains:write

Volver a sincronizar o editar BIMI. Vuelve a publicar desde los archivos subidos, o proporcione record_value para una anulación manual.

DELETE /domains/{domain_id}/bimi domains:write

Eliminar la configuración BIMI, los archivos alojados y el registro de Route53.

POST /domains/{domain_id}/bimi/svg-convert domains:read

Convertir y validar SVG para BIMI Tiny PS. Cuerpo: {"svg_content": "<svg...>"}

GET /domains/{domain_id}/bimi/vmc domains:read

Análisis VMC completo (DNS, cadena de certificados, validación). Use refresh=true en la consulta para omitir la caché.

POST /domains/{domain_id}/bimi/vmc/inspect domains:read

Inspeccionar un certificado PEM sin subirlo. Cuerpo: {"pem": "-----BEGIN CERTIFICATE-----..."}

GET /domains/{domain_id}/bimi/readiness domains:read

Lista de verificación de preparación BIMI/VMC con puntuación, estado del protocolo y aprobado/fallado por comprobación

API de MTA-STS

Gestionar MTA-STS y TLS-RPT alojados para un dominio. Se requiere el propietario del equipo para operaciones de escritura.

GET /domains/{domain_id}/mta-sts domains:read

Devuelve el estado de MTA-STS, el modo de la política, los objetivos CNAME del cliente, los registros DNS alojados y los metadatos de la comprobación de sincronización.

GET /domains/{domain_id}/mta-sts/web-file domains:read

Devuelve el contenido del archivo de política MTA-STS servido en https://mta-sts.{domain}/.well-known/mta-sts.txt.

POST /domains/{domain_id}/mta-sts/setup domains:write

Provisionar registros MTA-STS y TLS-RPT alojados. Crea una política predeterminada (mode: none) a partir de los registros MX en vivo cuando sea necesario.

PATCH /domains/{domain_id}/mta-sts/policy domains:write

Actualice la política MTA-STS. Proporcione el texto bruto policy o campos estructurados: mode, max_age y, opcionalmente, los nombres de host mx.

PATCH /domains/{domain_id}/mta-sts/mode domains:write

Actualizar solo el modo de la política. Cuerpo: {\"mode\": \"none|testing|enforce\"}. Las entradas MX se actualizan desde el DNS en vivo.

POST /domains/{domain_id}/mta-sts/reset domains:write

Restablecer la política a los valores predeterminados: mode: none, registros MX actuales, max_age: 604800.

POST /domains/{domain_id}/mta-sts/check domains:read

Ejecute la validación MTA-STS y TLS-RPT mediante el servicio de comprobación. Cuerpo opcional: verify_dns, require_caa, deploy_policy (predeterminado true al verificar DNS).

API de TLS-RPT

Configurar TLS-RPT alojado y consultar los informes TLS recibidos. Se requiere el propietario del equipo para las operaciones de escritura.

GET /domains/{domain_id}/tls-rpt domains:read

Devuelve la configuración TLS-RPT, los objetivos DNS, el estado de verificación y el recuento total de informes.

POST /domains/{domain_id}/tls-rpt/setup domains:write

Aprovisionar un TLS-RPT alojado en Route53 con la dirección de informes de Skysnag.

PATCH /domains/{domain_id}/tls-rpt domains:write

Vuelva a publicar el registro TLS-RPT alojado. Cuerpo opcional: record_value (debe comenzar con v=TLSRPTv1).

GET /domains/{domain_id}/tls-rpt/reports domains:read

Informes TLS paginados. Filtros: policy_domain, policy_mode, start_date, end_date.

GET /domains/{domain_id}/tls-rpt/reports/{report_id} domains:read

Obtener un único informe TLS mediante el ID de la base de datos o el UUID del informe.

GET /domains/{domain_id}/tls-rpt/by-source domains:read

Agrega sesiones TLS agrupadas por la IP del MTA remitente. Admite los mismos filtros de fecha y de política.

GET /domains/{domain_id}/tls-rpt/by-result domains:read

Agregar sesiones fallidas agrupadas por tipo de resultado TLS.

GET /domains/{domain_id}/tls-rpt/failures domains:read

Resumen de fallos TLS con totales de éxitos/errores y desglose por código de motivo del fallo.

GET /domains/{domain_id}/tls-rpt/failure-details domains:read

Filas paginadas con errores TLS (recuentos de errores distintos de cero o códigos de motivo de error)

API de puntuación de salud y seguridad del dominio

Read-only domain health, email security score, mail volume, sending services, failing sources, and cached dashboard data. All endpoints are scoped to {domain_id} and require domains:read. Volume/source endpoints accept optional start_date/end_date (YYYY-MM-DD, default last 30 days).

Obtener estado del dominio

get /domains/{domain_id}/health domains:read

Instantánea del estado actual del dominio: un mapa de aprobado/fallado por protocolo, una etiqueta cualitativa result, el proveedor de correo detectado y el registro DMARC en vivo. Proviene del último escaneo de Domain Guard; si no existe escaneo, se recurre a las verificaciones en vivo (el campo source indica cuál).

Devoluciones

source (guard_history | live), result, mail_provider, un mapa protocols de valores booleanos, protocols_passing/total_protocols, el dmarc_record y scanned_at.
Ejemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/health" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Respuesta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "source": "guard_history",
    "result": "Protected",
    "mail_provider": "Google Workspace",
    "protocols": {
      "dmarc": true,
      "spf": true,
      "mta_sts": true,
      "tls_rpt": true,
      "bimi": false
    },
    "protocols_passing": 4,
    "total_protocols": 5,
    "dmarc_record": "v=DMARC1; p=reject; rua=mailto:rua@example.com",
    "scanned_at": "2026-06-16T03:00:00Z"
  }
}

Obtener historial del estado del sistema

get /domains/{domain_id}/health/history domains:read

Historial paginado de instantáneas de estado de Domain Guard, las más recientes primero. Cada fila captura el estado de éxito/fallo del protocolo y la etiqueta de resultado en el momento del escaneo, permitiéndole trazar la protección a lo largo del tiempo.

Parámetros de consulta

  • start_date: OPCIONAL string · date

    Inicio inclusivo de la ventana (YYYY-MM-DD). Por defecto, hace 30 días.

  • end_date: OPCIONAL string · date

    Fin de la ventana inclusiva (YYYY-MM-DD). Por defecto, hoy.

  • page: OPCIONAL integer

    Número de página, basado en 1 (predeterminado: 1).

  • limit: OPCIONAL integer

    Elementos por página (1–100, predeterminado 25).

Devoluciones

Un array paginado de filas de snapshot (id, result, mail_provider, mapa protocols, protocols_passing/total_protocols, scanned_at) además de pagination.
Ejemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/health/history?page=1&limit=25" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Respuesta 
{
  "data": [
    {
      "id": 8841,
      "result": "Protected",
      "mail_provider": "Google Workspace",
      "protocols": { "dmarc": true, "spf": true, "mta_sts": true, "tls_rpt": true, "bimi": false },
      "protocols_passing": 4,
      "total_protocols": 5,
      "scanned_at": "2026-06-16T03:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 312,
    "has_more": true
  }
}

Obtener puntuación de seguridad

get /domains/{domain_id}/security-score domains:read

La puntuación actual de seguridad del correo electrónico (0–10) con una interpretación y un mensaje legibles por humanos. Se calcula bajo demanda a partir de resultados en caché de comprobadores externos, por lo que la primera llamada tras un fallo de caché puede ser más lenta. Devuelve 503 score_unavailable si no puede calcularse.

Devoluciones

score, max_score (10), interpretation (p. ej. excellent), un message y computed_at.
Ejemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/security-score" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Respuesta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "score": 9,
    "max_score": 10,
    "interpretation": "excellent",
    "message": "Your domain is well protected against spoofing and phishing.",
    "computed_at": "2026-06-16T12:30:00Z"
  }
}

Obtener historial de la puntuación de seguridad

get /domains/{domain_id}/security-score/history domains:read

Una serie de puntuación de seguridad derivada calculada a partir de instantáneas de Domain Guard, donde derived_score = passing protocols / 5 × 10. Úsela para una línea de tendencia cuando no necesite la puntuación completa del live-checker.

Parámetros de consulta

  • start_date: OPCIONAL string · date

    Inicio inclusivo de la ventana (YYYY-MM-DD). Por defecto, hace 30 días.

  • end_date: OPCIONAL string · date

    Fin de la ventana inclusiva (YYYY-MM-DD). Por defecto, hoy.

  • limit: OPCIONAL integer

    Número máximo de filas a devolver (1–100, valor predeterminado: 10).

Devoluciones

max_score, una note explicativa y un array history de puntos (derived_score, protocols_passing/total_protocols, result, scanned_at).
Ejemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/security-score/history?limit=30" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Respuesta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "max_score": 10,
    "note": "Derived from Domain Guard protocol coverage.",
    "history": [
      {
        "derived_score": 8,
        "protocols_passing": 4,
        "total_protocols": 5,
        "result": "Protected",
        "scanned_at": "2026-06-16T03:00:00Z"
      }
    ]
  }
}

Obtener volumen de correo electrónico

get /domains/{domain_id}/mail-volume domains:read

Historial diario del volumen de correo derivado de datos agregados DMARC: recuentos de entregados / en cuarentena / rechazados y resultado DMARC (aprobado/denegado) por día, además de totales acumulados para todo el periodo.

Parámetros de consulta

  • start_date: OPCIONAL string · date

    Inicio inclusivo de la ventana (YYYY-MM-DD). Por defecto, hace 30 días.

  • end_date: OPCIONAL string · date

    Fin de la ventana inclusiva (YYYY-MM-DD). Por defecto, hoy.

Devoluciones

Un objeto totals y un arreglo timeline, cada entrada indexada por date con volumen y recuentos de aprobados/no aprobados.
Ejemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/mail-volume?start_date=2026-05-01&end_date=2026-06-01" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Respuesta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "start_date": "2026-05-01",
    "end_date": "2026-06-01",
    "totals": {
      "total": 18432,
      "delivered": 18010,
      "quarantined": 280,
      "rejected": 142,
      "dmarc_pass": 17980,
      "dmarc_fail": 452
    },
    "timeline": [
      {
        "date": "2026-06-01",
        "total": 612,
        "delivered": 600,
        "quarantined": 8,
        "rejected": 4,
        "dmarc_pass": 600,
        "dmarc_fail": 12
      }
    ]
  }
}

Lista de servicios de envío

get /domains/{domain_id}/sending-services domains:read

Envío de fuentes con volumen, métricas DMARC, un porcentaje de compliance y un status de compliant, partial o failing. El indicador is_registered_threat marca fuentes conocidas como maliciosas.

Parámetros de consulta

  • start_date: OPCIONAL string · date

    Inicio inclusivo de la ventana (YYYY-MM-DD). Por defecto, hace 30 días.

  • end_date: OPCIONAL string · date

    Fin de la ventana inclusiva (YYYY-MM-DD). Por defecto, hoy.

  • limit: OPCIONAL integer

    Número máximo de filas a devolver (1–100, valor predeterminado: 10).

Devoluciones

Un array de services, cada uno con source_name, el objeto de métricas, compliance, status y is_registered_threat.
Ejemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/sending-services?limit=10" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Respuesta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "services": [
      {
        "source_name": "Google",
        "total_count": 12040,
        "dmarc": { "pass": 12010, "fail": 30 },
        "compliance": 99.75,
        "status": "compliant",
        "is_registered_threat": false
      }
    ]
  }
}

Listar fuentes fallidas

get /domains/{domain_id}/failed-sources domains:read

Fuentes que no cumplieron la alineación DMARC en el período, ordenadas por volumen de fallos. Estas son las fuentes de mayor prioridad para investigar: remitentes legítimos cuya autenticación debe corregirse, o suplantadores.

Parámetros de consulta

  • start_date: OPCIONAL string · date

    Inicio inclusivo de la ventana (YYYY-MM-DD). Por defecto, hace 30 días.

  • end_date: OPCIONAL string · date

    Fin de la ventana inclusiva (YYYY-MM-DD). Por defecto, hoy.

  • limit: OPCIONAL integer

    Número máximo de filas a devolver (1–100, valor predeterminado: 10).

Devoluciones

Una matriz de failed_sources con la misma estructura que sending-services, ordenada por volumen de fallos de mayor a menor.
Ejemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/failed-sources?limit=10" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Respuesta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "failed_sources": [
      {
        "source_name": "Unknown",
        "total_count": 420,
        "dmarc": { "pass": 0, "fail": 420 },
        "compliance": 0,
        "status": "failing",
        "is_registered_threat": true
      }
    ]
  }
}

Obtener caché del panel

get /domains/{domain_id}/dashboard-cache domains:read

Devuelve la carga útil (payload) de la instantánea del panel precomputada para el dominio, si existe. Esta es la forma más rápida de renderizar un panel sin volver a recalcular los agregados. Cuando no existe ninguna instantánea, cached es false y data es null.

Parámetros de consulta

  • start_date: OPCIONAL string · date

    Inicio inclusivo de la ventana (YYYY-MM-DD). Por defecto, hace 30 días.

  • end_date: OPCIONAL string · date

    Fin de la ventana inclusiva (YYYY-MM-DD). Por defecto, hoy.

Devoluciones

cached (booleano), cached_at, la ventana solicitada y la carga útil (payload) de la instantánea data (o null).
Ejemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/dashboard-cache" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Respuesta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "cached": true,
    "cached_at": "2026-06-16T03:05:00Z",
    "start_date": "2026-05-17",
    "end_date": "2026-06-16",
    "data": { "summary": { "total_count": 18432 } }
  }
}

API de cronología de DNS

Read-only DNS connect/disconnect timeline, current records, record-value history, change events, and stored snapshots. All endpoints are scoped to {domain_id} and require domains:read. Filterable by record_type and start_date/end_date (YYYY-MM-DD).

Obtener la línea de tiempo del DNS

get /domains/{domain_id}/dns/timeline domains:read

Un resumen de estado por protocolo (estado actual, marcas de tiempo de la última conexión/desconexión y recuentos de conexiones) más los eventos más recientes de conexión/desconexión. Esta es la vista principal de cómo cada registro de protocolo se ha conectado y desconectado a lo largo del tiempo.

Parámetros de consulta

  • record_type: OPCIONAL string

    Filtra eventos por uno de los siguientes: dmarc, spf, mta_sts, tls_rpt, bimi.

  • action: OPCIONAL string

    Filtrar por connected o disconnected.

  • start_date: OPCIONAL string · date

    Inicio inclusivo de la ventana (YYYY-MM-DD). Por defecto, hace 30 días.

  • end_date: OPCIONAL string · date

    Fin de la ventana inclusiva (YYYY-MM-DD). Por defecto, hoy.

  • limit: OPCIONAL integer

    Número máximo de filas a devolver (1–100, valor predeterminado: 10).

Devoluciones

Un summary indexado por protocolo y un array events (id, record_type, action, record_value, status_before/status_after, occurred_at).
Ejemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/dns/timeline?limit=50" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Respuesta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "summary": {
      "dmarc": {
        "current_status": "connected",
        "last_connected": "2026-05-02T10:15:00Z",
        "last_disconnected": null,
        "connection_count": 2,
        "disconnection_count": 1
      }
    },
    "events": [
      {
        "id": 5521,
        "record_type": "dmarc",
        "action": "connected",
        "record_value": "v=DMARC1; p=reject; rua=mailto:rua@example.com",
        "status_before": "disconnected",
        "status_after": "connected",
        "occurred_at": "2026-05-02T10:15:00Z"
      }
    ]
  }
}

Obtener la configuración DNS actual

get /domains/{domain_id}/dns/current domains:read

El estado actual de cada registro de protocolo: estado de conexión, indicador de verificación, marcas de tiempo de última conexión/desconexión y el último valor conocido del registro. SPF además informa su DNS lookup_count (el límite de 10 consultas DNS influye en la validez).

Devoluciones

Un mapa protocols indexado por protocolo, cada entrada con current_status, verified, status, last_connected/last_disconnected y record_value.
Ejemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/dns/current" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Respuesta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "protocols": {
      "dmarc": {
        "current_status": "connected",
        "verified": true,
        "status": "valid",
        "last_connected": "2026-05-02T10:15:00Z",
        "last_disconnected": null,
        "record_value": "v=DMARC1; p=reject; rua=mailto:rua@example.com"
      },
      "spf": {
        "current_status": "connected",
        "verified": true,
        "record_value": "v=spf1 include:_spf.google.com -all",
        "lookup_count": 3
      }
    }
  }
}

Obtener historial de DNS

get /domains/{domain_id}/dns/history domains:read

Un historial unificado, paginado y cronológico de los valores de los registros — fusionando instantáneas de DMARC y SPF para que pueda ver exactamente qué contenía cada registro en cada momento. Las filas SPF incluyen lookup_count.

Parámetros de consulta

  • record_type: OPCIONAL string

    Limitar a dmarc o spf (por defecto: ambos).

  • start_date: OPCIONAL string · date

    Inicio inclusivo de la ventana (YYYY-MM-DD). Por defecto, hace 30 días.

  • end_date: OPCIONAL string · date

    Fin de la ventana inclusiva (YYYY-MM-DD). Por defecto, hoy.

  • page: OPCIONAL integer

    Número de página, basado en 1 (predeterminado: 1).

  • limit: OPCIONAL integer

    Elementos por página (1–100, predeterminado 25).

Devoluciones

Un array paginado de filas de historial (record_type, record_value, occurred_at; SPF añade lookup_count) más pagination.
Ejemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/dns/history?record_type=spf&page=1&limit=25" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Respuesta 
{
  "data": [
    {
      "record_type": "spf",
      "record_value": "v=spf1 include:_spf.google.com -all",
      "lookup_count": 3,
      "occurred_at": "2026-05-02T10:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 312,
    "has_more": true
  }
}

Listar cambios de DNS

get /domains/{domain_id}/dns/changes domains:read

Un feed paginado de eventos de conexión/desconexión de cambio a través de todos los protocolos, con la transición de estado (status_before → status_after). Use esto para un feed de actividad estilo auditoría sobre la salud del DNS.

Parámetros de consulta

  • record_type: OPCIONAL string

    Uno de dmarc, spf, mta_sts, tls_rpt, bimi.

  • action: OPCIONAL string

    Filtrar por connected o disconnected.

  • start_date: OPCIONAL string · date

    Inicio inclusivo de la ventana (YYYY-MM-DD). Por defecto, hace 30 días.

  • end_date: OPCIONAL string · date

    Fin de la ventana inclusiva (YYYY-MM-DD). Por defecto, hoy.

  • page: OPCIONAL integer

    Número de página, basado en 1 (predeterminado: 1).

  • limit: OPCIONAL integer

    Elementos por página (1–100, predeterminado 25).

Devoluciones

Un array paginado de eventos de cambio (id, record_type, action, record_value, status_before/status_after, occurred_at) además de pagination.
Ejemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/dns/changes?action=disconnected&page=1&limit=25" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Respuesta 
{
  "data": [
    {
      "id": 5520,
      "record_type": "spf",
      "action": "disconnected",
      "record_value": null,
      "status_before": "connected",
      "status_after": "disconnected",
      "occurred_at": "2026-04-28T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 312,
    "has_more": true
  }
}

Listar instantáneas DNS

get /domains/{domain_id}/dns/snapshots domains:read

Las filas crudas de snapshot almacenadas, agrupadas por tipo de registro. A diferencia de /dns/history (que fusiona y pagina), esto devuelve por separado los arrays de snapshot subyacentes dmarc y spf.

Parámetros de consulta

  • record_type: OPCIONAL string

    Limitar a dmarc o spf (por defecto: ambos).

  • start_date: OPCIONAL string · date

    Inicio inclusivo de la ventana (YYYY-MM-DD). Por defecto, hace 30 días.

  • end_date: OPCIONAL string · date

    Fin de la ventana inclusiva (YYYY-MM-DD). Por defecto, hoy.

  • limit: OPCIONAL integer

    Número máximo de filas a devolver (1–100, valor predeterminado: 10).

Devoluciones

Un array dmarc y un array spf de filas de instantánea (id, record_value, occurred_at; SPF añade lookup_count).
Ejemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/dns/snapshots?limit=50" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Respuesta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "dmarc": [
      {
        "id": 331,
        "record_value": "v=DMARC1; p=reject; rua=mailto:rua@example.com",
        "occurred_at": "2026-05-02T10:15:00Z"
      }
    ],
    "spf": [
      {
        "id": 902,
        "record_value": "v=spf1 include:_spf.google.com -all",
        "lookup_count": 3,
        "occurred_at": "2026-05-02T10:15:00Z"
      }
    ]
  }
}

API de registros de auditoría

Read-only account API audit logs — every mutating API request (POST/PUT/PATCH/DELETE) plus sensitive reads are recorded with method, path, status, IP, token, and timestamp. Scoped to the token owner's account and require the account:read scope.

The audit log object

Cada endpoint en esta sección devuelve filas con esta forma. action es una etiqueta estable y legible por humanos para la operación; request_id coincide con la request_id que se refleja en el sobre de respuesta de la llamada original.

Objeto del registro de auditoría 
{
  "id": 90122,
  "request_id": "req_8f2c1a4e",
  "action": "domain.hosted_spf.update",
  "method": "PATCH",
  "path": "/api/v1/domains/123/hosted-spf",
  "status_code": 200,
  "ip_address": "203.0.113.24",
  "token_id": 12,
  "token_name": "CI deploy token",
  "user_id": 45,
  "team_id": 9,
  "created_at": "2026-06-16T11:02:33Z"
}

Listar registros de auditoría

get /audit-logs account:read

Registros de auditoría paginados para la cuenta, los más recientes primero. Combine filtros para restringir el feed — p. ej., todas las escrituras fallidas en un rango de fechas.

Parámetros de consulta

  • method: OPCIONAL string

    Método HTTP, p. ej. POST.

  • action: OPCIONAL string

    Etiqueta de acción exacta, por ejemplo: domain.hosted_spf.update.

  • path: OPCIONAL string

    Coincidencia de subcadena en la ruta de la solicitud.

  • status_code: OPCIONAL integer

    Estado HTTP exacto, p. ej. 200.

  • status_class: OPCIONAL string

    Familia de códigos de estado: 2xx, 3xx, 4xx, 5xx.

  • ip_address: OPCIONAL string

    IP exacta del cliente

  • token_id: OPCIONAL integer

    Filtrar por un único token de API.

  • q: OPCIONAL string

    Búsqueda de texto libre en acción, ruta y dirección IP.

  • start_date: OPCIONAL string · date

    Inicio de ventana inclusivo (YYYY-MM-DD).

  • end_date: OPCIONAL string · date

    Fin de ventana inclusivo (YYYY-MM-DD).

  • page: OPCIONAL integer

    Número de página (predeterminado: 1).

  • limit: OPCIONAL integer

    Elementos por página (1–100, predeterminado 25).

Devoluciones

Un array paginado de objetos de registro de auditoría más un objeto pagination.
Ejemplo 
curl -s "https://developers.skysnag.com/api/v1/audit-logs?page=1&limit=25" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Respuesta 
{
  "data": [
    {
      "id": 90122,
      "request_id": "req_8f2c1a4e",
      "action": "domain.hosted_spf.update",
      "method": "PATCH",
      "path": "/api/v1/domains/123/hosted-spf",
      "status_code": 200,
      "ip_address": "203.0.113.24",
      "token_id": 12,
      "token_name": "CI deploy token",
      "user_id": 45,
      "team_id": 9,
      "created_at": "2026-06-16T11:02:33Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 312,
    "has_more": true
  }
}

Obtener registro de auditoría

get /audit-logs/{log_id} account:read

Recupera una única entrada del registro de auditoría por ID, limitada a la cuenta. Devuelve 404 not_found si la entrada no pertenece a la cuenta autenticada.

Parámetros de ruta

  • log_id: requerido integer

    El identificador de la entrada del registro de auditoría.

Devoluciones

Un único objeto de registro de auditoría.
Ejemplo 
curl -s "https://developers.skysnag.com/api/v1/audit-logs/90122" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Respuesta 
{
  "data": {
    "id": 90122,
    "request_id": "req_8f2c1a4e",
    "action": "domain.hosted_spf.update",
    "method": "PATCH",
    "path": "/api/v1/domains/123/hosted-spf",
    "status_code": 200,
    "ip_address": "203.0.113.24",
    "token_id": 12,
    "token_name": "CI deploy token",
    "user_id": 45,
    "team_id": 9,
    "created_at": "2026-06-16T11:02:33Z"
  }
}

Gestión de tokens

GET /auth/tokens tokens:read

Lista los tokens activos de la cuenta. Admite page y limit.

cURL 
curl -s "https://developers.skysnag.com/api/v1/auth/tokens?page=1&limit=25" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here"
POST /auth/tokens tokens:write

Crear un token. El valor completo se devuelve una sola vez en data.plain_text.

CampoTipoDescripción
nombre obligatoriostringEtiqueta del token
alcances obligatorioArray de cadenasDesde GET /auth/scopes
Expira en {n} díasEnteroOpcional 1–365 días
cURL 
curl -s "https://developers.skysnag.com/api/v1/auth/tokens" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here" \
  -d '{
    "name": "CI token",
    "scopes": ["account:read"],
    "expires_in_days": 90
  }'

¿Necesita ayuda? Contáctenos support@skysnag.com y incluir el request_id desde cualquier respuesta de error. Descargar la colección de Postman probar endpoints de forma interactiva