API para desarrolladores

Una sola API REST para listas, campañas, email transaccional… y la IA.

Primeros pasos

Todos los planes de pago incluyen acceso completo a la API REST. Genera una clave en tu cuenta, en Cuenta → Claves de API, y envíala con cada solicitud:

curl -H "X-Api-Key: YOUR_KEY" https://mailflow.top/api/index.php/lists

URL base: https://mailflow.top/api/index.php · Las respuestas son JSON con un campo status con valor success o error. La API no está disponible en el plan gratuito.

Recursos principales

La plataforma es compatible con MailWizz, así que toda la API principal —listas, suscriptores, segmentos, campos personalizados, campañas, seguimiento, plantillas, email transaccional, rebotes y bajas— está documentada de forma interactiva (OpenAPI), junto con todos los endpoints de MailFlow de esta página, en:

→ Referencia interactiva de la API (OpenAPI)

Los SDK de MailWizz existentes (p. ej., el SDK de PHP oficial) funcionan sin configuración adicional: solo tienes que apuntarlos a la URL base indicada arriba.

Endpoints de IA

Las funciones de IA son ciudadanas de primera clase en la API: la misma clave, la misma autenticación y los mismos límites de plan y consumo de créditos que en la aplicación web.

GET /ai/credits

Tu contador de créditos de IA del mes en curso. Los créditos son por mes de facturación y los no utilizados no se acumulan al mes siguiente.

{"status":"success","data":{"unlimited":false,"limit":750,"used":112,"remaining":638}}

GET /ai/replies

Clasificaciones de Smart Replies para tus campañas: alimenta tu CRM con quién está interesado, quién hizo una pregunta y quién se quejó. Filtros: category (interested, question, complaint, unsubscribe_request, auto_reply, out_of_office, bounce, other), campaign_uid, since (YYYY-MM-DD), page, per_page (máx. 50).

curl -H "X-Api-Key: YOUR_KEY" \
  "https://mailflow.top/api/index.php/ai/replies?category=interested&since=2026-08-01"

{"status":"success","data":{"count":42,"current_page":1,"per_page":20,"total_pages":3,
  "records":[{"from_email":"[email protected]","subject":"RE: your offer",
    "category":"interested","confidence":98,"engine":"embeddings",
    "summary":"...","suggested_reply":"...","date_added":"2026-08-24 18:21:19",
    "campaign_uid":"py794hjqk8a8d"}]}}

GET /ai/tiers

Niveles de interacción de IA (vip, engaged, passive, at_risk, dormant) por lista: la misma puntuación que impulsa el piloto automático y la recuperación.

{"status":"success","data":{"records":[
  {"list_uid":"qk661oq7nl8c1","name":"Main list","tiers":{"engaged":1200,"passive":3400,"dormant":900}}]}}

POST /ai/subject-lines

Genera líneas de asunto en cualquier idioma. Cuerpo: topic (obligatorio), count (1–5, 3 por defecto), language (opcional). Consume créditos de IA igual que el editor web.

curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"topic":"Summer sale for B2B customers","count":3,"language":"Greek"}' \
  https://mailflow.top/api/index.php/ai/subject-lines

{"status":"success","data":{"subjects":["...","...","..."],"credits_remaining":636}}

GET /ai/flows · POST /ai/flows/author · POST /ai/flows/<uid>/enroll · POST /ai/flows/<uid>/status

El creador de flujos con IA a través de la API: lista tus flujos con contadores en tiempo real; haz que la IA cree un flujo completo a partir de un objetivo en lenguaje natural ({"goal":"...","list_uid":"..."}, que devuelve un borrador que activas con {"status":"active"}); inscribe a un suscriptor en un flujo ({"email":"..."}).

curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"goal":"When someone replies interested, notify me, wait 2 days, then send a case study"}' \
  https://mailflow.top/api/index.php/ai/flows/author

Crea tu propia aplicación sobre MailFlow

Todo lo que haces en la aplicación web se puede hacer mediante la API, así que puedes gestionar MailFlow desde tu propio software. Un flujo típico:

  1. Crea una lista y añade contactos: POST /lists, POST /lists/<list_uid>/subscribers/bulk.
  2. Encuentra nuevos contactos con DataStack: POST /datastack/import.
  3. Crea una campaña tú mismo (POST /campaigns) o deja que la IA la escriba: POST /ai/campaigns.
  4. Revisa y programa el borrador de la IA: GET /ai/campaigns/<run_id>, POST /ai/campaigns/<run_id>/approve.
  5. Consulta los resultados: GET /analytics/campaigns, GET /campaigns/<campaign_uid>/clicks.

Las tareas largas (redacción con IA, lectura de sitios web, importaciones de DataStack) se ejecutan en segundo plano: la llamada responde 202 con un job_id, y GET /ai/jobs/<job_id> te indica cuándo ha terminado.

Analítica

Las mismas cifras que tu panel y tus informes de campaña. Las fechas están en UTC; from y to (YYYY-MM-DD) abarcan por defecto los últimos 30 días. Los totales de la cuenta se actualizan cada pocos minutos.

  • GET /analytics/overview — listas, suscriptores, campañas y resultados de envío de un periodo: enviados, entregados, aperturas, clics, rebotes, quejas, bajas y sus tasas.
  • GET /analytics/timeline — los mismos resultados por día (o por hora con interval=hour), además de los nuevos suscriptores.
  • GET /analytics/campaigns — una fila por campaña con sus resultados; filtra con status.
  • GET /campaigns/<campaign_uid>/opens y /clicks — quién abrió o hizo clic, cuándo, desde dónde y con qué dispositivo (unique=1 solo para los primeros eventos).
  • GET /campaigns/<campaign_uid>/links, /locations, /devices, /timeline, /abuse-reports — clics por enlace, resultados por país y ciudad, por tipo de dispositivo y por hora, e informes de abuso.
  • GET /campaigns/<campaign_uid>/stats, /bounces, /unsubscribes, /complaints, /delivery-logs — los informes básicos de campaña.
  • GET /lists/<list_uid>/stats — suscriptores por estado y origen, crecimiento diario y las campañas enviadas a la lista.
curl -H "X-Api-Key: YOUR_KEY" \
  "https://mailflow.top/api/index.php/analytics/overview?from=2026-09-01&to=2026-09-30"

{"status":"success","data":{"period":{"from":"2026-09-01","to":"2026-09-30","timezone":"UTC"},
  "lists":9,"subscribers":{"total":52040,"confirmed":50102,"unsubscribed":311},
  "campaigns":{"total":24,"sent":20,"draft":4},
  "activity":{"sent":48210,"delivered":47650,"unique_opens":14230,"unique_clicks":2210,
    "bounces":402,"complaints":3,"unsubscribes":95,"open_rate":29.86,"click_rate":4.64}}}

Cuenta y configuración de envío

  • GET /account · PUT /account — tu perfil, plan, cuota de envío y límites; actualiza tu nombre, teléfono o zona horaria.
  • GET|POST /campaign-groups · GET|PUT|DELETE /campaign-groups/<group_uid> — grupos de campañas.
  • GET|POST /suppression-lists · GET|PUT|DELETE /suppression-lists/<list_uid> · GET|POST|DELETE /suppression-lists/<list_uid>/emails — listas de supresión (hasta 10.000 emails por llamada).
  • GET|POST /blacklist · DELETE /blacklist/<email_uid> · GET /blacklist/check?email= — tu lista negra y si una dirección está bloqueada en algún lugar.
  • GET|POST /sending-domains · GET|DELETE /sending-domains/<id> · POST /sending-domains/<id>/verify — dominios de envío con los registros DKIM, SPF y DMARC que debes publicar.
  • GET|POST /tracking-domains · GET|DELETE /tracking-domains/<id> · POST /tracking-domains/<id>/verify — tus propios dominios de seguimiento de enlaces.
  • GET /delivery-servers · GET /countries — los servidores a través de los que puedes enviar y los países con sus zonas.

Campañas de IA

Deja que la IA escriba campañas por ti, con o sin tu revisión. La IA usa el perfil de tu negocio, elige la audiencia y la hora de envío, comprueba el email frente a los filtros de spam y lo escribe en el idioma de cada suscriptor.

  • POST /ai/campaigns — dile a la IA qué enviar: goal (obligatorio), list_uid (una lista, auto o prospects), audience, business, template_uid, follow_up, auto_send.
  • POST /ai/campaigns/prepare — la IA decide qué enviar a continuación (hasta 3 al día); hint opcional.
  • GET /ai/campaigns · GET /ai/campaigns/<run_id> — campañas de IA con asuntos, audiencia, hora propuesta y comprobación de spam (html=1 añade el email).
  • POST /ai/campaigns/<run_id>/approve — programa la campaña: when = proposed, now o custom con send_at; max_send opcional.
  • POST /ai/campaigns/<run_id>/revise (con feedback) · POST /ai/campaigns/<run_id>/discard — pide cambios o descarta el borrador.
  • GET /ai/jobs/<job_id> — estado de una tarea en segundo plano y las campañas de IA que ha creado.
  • GET|PUT /ai/hands-off — modo sin intervención: la IA planifica, redacta y envía sin esperarte ({"enabled":true}).
curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"goal":"Invite our customers to the autumn webinar","list_uid":"auto"}' \
  https://mailflow.top/api/index.php/ai/campaigns

{"status":"success","data":{"job_id":512,"job_status":"queued","check":"/ai/jobs/512"}}

curl -H "X-Api-Key: YOUR_KEY" https://mailflow.top/api/index.php/ai/jobs/512

{"status":"success","data":{"job_id":512,"type":"autopilot","status":"done","ai_campaigns":[331],"sent":false}}

Perfiles de negocio

La IA escribe en nombre de tu negocio. Mantén un perfil por sitio web:

  • GET|POST /ai/businesses — tus negocios; añade uno con website.
  • GET|PUT|DELETE /ai/businesses/<domain> — perfil, remitente (from_name, from_email, reply_to) y datos de la empresa (company_*).
  • POST /ai/businesses/<domain>/read-website · PUT /ai/businesses/<domain>/main — deja que la IA lea el sitio web y rellene el perfil; márcalo como tu negocio principal.

Clientes potenciales con DataStack

Encuentra direcciones de email profesionales y personales nuevas e impórtalas directamente en tus listas. Las importaciones se descuentan de tu plan; los recuentos son gratuitos.

  • GET /datastack/credits — cuántas direcciones te permite importar todavía tu plan este mes.
  • GET /datastack/count — cuántas direcciones hay para country, niche (categorías de negocio), keyword y role (personales). Gratis.
  • POST /datastack/import — importa direcciones business y/o personal en list_uid (tarea en segundo plano). Las direcciones nuevas se verifican antes de que cualquier campaña les envíe un email.
curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"list_uid":"cr5899rtqe668","business":2000,"country":"Greece","niche":"dentist, hotel"}' \
  https://mailflow.top/api/index.php/datastack/import

{"status":"success","data":{"job_id":513,"job_status":"queued","check":"/ai/jobs/513","list_uid":"cr5899rtqe668"}}

Tickets de soporte

  • GET|POST /support-tickets — tus tickets; abre uno con subject, message, category y priority.
  • GET /support-tickets/<ticket_uid> · POST /support-tickets/<ticket_uid>/replies · PUT /support-tickets/<ticket_uid>/close — lee la conversación, responde, cierra.

Permisos de las claves de API

Una clave puede limitarse a ciertos endpoints. En Cuenta → Claves de API, edita la clave, activa los permisos y marca lo que puede usar. Los endpoints de esta página aparecen con el prefijo MailFlow.

Errores y límites

  • 400 — X-Api-Key ausente o no válido, o la clave no tiene permiso para este endpoint
  • 402 — no te quedan suficientes créditos de DataStack este mes
  • 403 — la función no está incluida en tu plan o se ha alcanzado un límite del plan
  • 404 — la lista, campaña u otro elemento no existe en tu cuenta
  • 409 — el elemento no está en el estado adecuado (por ejemplo, solo se pueden aprobar borradores)
  • 422 — parámetros ausentes o no válidos
  • 429 — se ha alcanzado el límite de créditos de IA o la asignación mensual de IA; se restablece en tu próxima fecha de facturación

Las ráfagas se limitan por clave: implementa un reintento con espera exponencial (exponential backoff) ante un 429. ¿Tienes preguntas? Contáctanos o abre un ticket de soporte.