Saltar al contenido

Consultar la cuenta y estadísticas

Saca por API de solo lectura todo lo de tu cuenta de Vemudo: resumen y uso del plan, listado de emails con filtros, eventos, estadísticas por día, dominios, contactos y campañas.

Por Equipo Vemudo · Actualizado el

Todo lo que ves en el panel sobre tu cuenta se puede consultar por API con una clave read (o full). Las consultas son de solo lectura y siempre de tu propia organización: ningún endpoint acepta un id de organización.

Si necesitas que un asistente de IA consulte tu cuenta sin poder cambiar nada, esta es la API que usa: ver MCP y asistentes de IA.

Reglas comunes

  • Aislamiento. Un id de otra organización, de otro entorno o mal formado devuelve 404 not_found, igual que uno inexistente.
  • Entornos. Los recursos de envío (emails, eventos, estadísticas y webhooks) son solo los del entorno de la clave: una clave test no ve emails live, ni al revés. Los recursos de la organización (cuenta, dominios, contactos, listas, segmentos, campañas, plantillas y bajas) los ve cualquier clave con permiso de lectura, test o live.
  • Sin secretos. Nunca se devuelven hashes de claves, secretos de webhook (solo enmascarados), cuerpos de email ni datos personales de los miembros del panel.
  • Formato. JSON en camelCase, fechas en ISO 8601 UTC y estados en minúsculas.
  • Sin caché. Las respuestas llevan Cache-Control: no-store.
  • Errores. application/problem+json con un code estable. Ver Errores y límites.

Paginación

Los listados devuelven:

json
{ "data": [], "nextCursor": "..." }

limit va de 1 a 100 (25 por defecto). Dominios, listas y segmentos no se paginan (son pocos) y devuelven siempre nextCursor: null. Mientras nextCursor no sea null, pásalo como cursor en la siguiente petición. El cursor es opaco: no lo construyas ni lo interpretes.

bash
curl "https://api.vemudo.com/v1/emails?limit=100&cursor=$NEXT" \
  -H "Authorization: Bearer $VEMUDO_API_KEY"

Resumen de la cuenta

bash
curl https://api.vemudo.com/v1/account -H "Authorization: Bearer $VEMUDO_API_KEY"

Una sola llamada devuelve:

  • organization: id, nombre, estado y fecha de alta.
  • plan y subscription: tu plan (código, nombre, emails incluidos) y el estado y periodo de la suscripción, o null si no tienes.
  • period: el periodo de facturación actual.
  • usage: emails enviados, incluidos, restantes, reservados (programados), tope (cap) y política de excedente (overagePolicy). Son los mismos cálculos que el panel, incluido el tope mensual propio si tu organización lo tiene.
  • limits: límites de envío por segundo, por día y por mes.
  • counts: número de dominios (y verificados), contactos, listas, segmentos, campañas, plantillas y webhooks.
  • apiKey: la clave que has usado (id, nombre, prefijo, entorno y scopes).

Emails enviados

bash
curl "https://api.vemudo.com/v1/emails?status=bounced,complained&since=2026-11-01T00:00:00Z" \
  -H "Authorization: Bearer $VEMUDO_API_KEY"

GET /v1/emails lista los emails del entorno de la clave, del más reciente al más antiguo. Filtros opcionales, combinables:

ParámetroQué filtra
statusUno o varios estados separados por comas (delivered,bounced).
toDestinatario: exacto si lleva @; si no, empieza por (mín. 3).
fromDirección exacta del remitente.
subjectAsuntos que contienen el texto (mín. 3 caracteres).
tagEtiqueta nombre:valor, o solo nombre.
campaignId, templateId, apiKeyIdPor campaña, plantilla o clave que lo creó.
originapi, test_send o campaign.
since, untilRango ISO 8601 sobre la creación (until con solo fecha = todo el día).

Cada elemento es el mismo objeto que devuelve GET /v1/emails/{id}, sin los eventos. El cuerpo del email no se expone por la API.

Para la línea de eventos de uno concreto (necesita read o full; una clave send ve el email pero no este listado):

bash
curl https://api.vemudo.com/v1/emails/$ID/events -H "Authorization: Bearer $VEMUDO_API_KEY"

Estadísticas

bash
curl "https://api.vemudo.com/v1/stats?since=2026-10-05&until=2026-11-04" \
  -H "Authorization: Bearer $VEMUDO_API_KEY"

Devuelve las cifras por día UTC del entorno de la clave:

  • days: una entrada por día con requested, sent, delivered, bounced, complained, failed, suppressed, cancelled, opened, clicked y unsubscribed. Los días sin actividad salen con ceros.
  • totals: la suma del periodo.
  • rates: tasas en % con 2 decimales (null si no hay base). Entrega y rebote se calculan sobre sent; queja, apertura y clic sobre delivered.

Cada email cuenta en el día UTC en que se creó, aunque se entregue o rebote después.

since y until son fechas YYYY-MM-DD. Por defecto son los últimos 30 días y el máximo son 92. Puedes acotar por campaignId o por domain (el dominio del remitente).

Las aperturas y los clics son señales aproximadas, como se explica en Campañas e informe.

Dominios, contactos, listas y segmentos

bash
curl https://api.vemudo.com/v1/domains   -H "Authorization: Bearer $VEMUDO_API_KEY"
curl https://api.vemudo.com/v1/contacts  -H "Authorization: Bearer $VEMUDO_API_KEY"
curl https://api.vemudo.com/v1/lists     -H "Authorization: Bearer $VEMUDO_API_KEY"
curl https://api.vemudo.com/v1/segments  -H "Authorization: Bearer $VEMUDO_API_KEY"

Cada uno tiene su detalle por id. Los contactos filtran por q, status, listId y tag. Más información en Dominios y DNS y Contactos, listas y segmentos.

Campañas

GET /v1/campaigns y GET /v1/campaigns/{id} devuelven las campañas con sus métricas (destinatarios, enviados, entregados, rebotes, quejas, aperturas, clics, bajas y tasas) como el informe del panel. El detalle incluye los enlaces más pulsados.

Plantillas, bajas y webhooks

GET /v1/templates, GET /v1/suppressions y GET /v1/webhooks también se pueden leer con read. Ver Plantillas, Bajas y supresiones y Eventos y webhooks.

Límites de estas consultas

Vale el límite de 10 peticiones por segundo de la organización. GET /v1/stats, GET /v1/account, segmentos y campañas (calculan recuentos en vivo) admiten además 60 peticiones por minuto por clave, y las consultas pesadas tienen un tiempo máximo de 3 segundos: si tienes mucho volumen, acota el rango de fechas.

Ejemplo: tasa de rebote de la semana

js
const res = await fetch('https://api.vemudo.com/v1/stats?since=2026-10-29&until=2026-11-04', {
  headers: { Authorization: `Bearer ${process.env.VEMUDO_API_KEY}` },
});
const { totals, rates } = await res.json();
console.log(`Enviados: ${totals.sent}, rebote: ${rates.bounce}`);