Descripción general de la API REST

Los SDK cubren la mayoría de las necesidades, pero todo lo que hacen es HTTPS + JSON normal y corriente que puedes llamar desde cualquier lenguaje. La referencia completa y generada de cada endpoint está en la referencia de la API REST.

URL base

https://api.frontmail.dev

Todos los endpoints están versionados bajo /v1. Los alias compatibles con EmailJS POST /api/v1.0/email/send y POST /api/v1.0/email/send-form se comportan como /v1/send y /v1/send-form.

Autenticación

Clave	Cómo se envía	Endpoints permitidos
Clave pública pk_…	Cabecera X-Frontmail-Public-Key: pk_… o user_id en el cuerpo	POST /v1/send, POST /v1/send-form, POST /v1/uploads, GET /v1/messages/:id con la cabecera X-Frontmail-Status-Token
Clave privada sk_…	Cabecera Authorization: Bearer sk_… o accessToken en el cuerpo; solo desde servidores (una solicitud con cabecera Origin recibe 403 private_key_in_browser)	todos los endpoints

Las solicitudes con clave pública sin Origin ni Referer (servidores, curl, apps nativas) necesitan Permitir apps móviles; de lo contrario reciben 403 origin_not_allowed.

GET /v1/health y GET /v1/public-config no necesitan clave. Consulta Claves públicas y privadas para conocer el modelo de seguridad.

Endpoints

Método y ruta	Para qué sirve
POST /v1/send	Envía un correo a partir de una plantilla (JSON)
POST /v1/send-form	Envía un correo desde multipart/form-data (los archivos se convierten en adjuntos)
POST /v1/send-batch	Envía hasta 100 correos (clave privada)
POST /v1/uploads	Obtiene una URL prefirmada para un adjunto grande
GET /v1/messages/:id	Estado y eventos de un mensaje
GET /v1/history	Historial de mensajes paginado (clave privada)
GET /v1/templates, GET /v1/templates/:id	Plantillas con sus esquemas de parámetros (clave privada)
GET /v1/public-config	Configuración pública, sin clave: la site key de Turnstile para móviles de Frontmail y la URL de la página, que usa @frontmail/react-native (se puede cachear 1 hora)
GET /v1/health	Comprobación de estado

Cabeceras

Cabecera	Dirección	Significado
Idempotency-Key	solicitud	Deduplica los reintentos durante 24 h (≤ 255 caracteres); consulta Reintentos e idempotencia
X-Frontmail-Client	solicitud	Nombre y versión del SDK, p. ej. @frontmail/browser/0.3.1 (opcional, ayuda al soporte)
X-Frontmail-Status-Token	solicitud	status_token de la respuesta del envío, para GET /v1/messages/:id con clave pública. El antiguo parámetro de consulta ?token= sigue funcionando, pero acaba en los registros de acceso; mejor usa la cabecera
Retry-After	respuesta	Segundos que hay que esperar, en un 429

Ejemplo

curl https://api.frontmail.dev/v1/send \
  -H 'Content-Type: application/json' \
  -H 'X-Frontmail-Public-Key: pk_4f2a…' \
  -H 'Origin: https://example.com' \
  -H 'Idempotency-Key: 5f0c6f8e-1d2a-4c55-9f6b-2d7c1f4a9e10' \
  -d '{
    "service_id": "svc_01J9…",
    "template_id": "tpl_01J9…",
    "template_params": { "name": "Jana", "email": "jana@example.com", "message": "Hi!" },
    "turnstile_token": "0.AbCd…"
  }'

{ "message_id": "msg_01J9Z3K7Q2", "status": "queued", "status_token": "st_…", "locale": "en" }

status es queued o held (sin créditos en el modo hold). Ambos significan que el mensaje se ha aceptado; el código de respuesta es 202.

Para enviar el correo en un idioma de la plantilla, añade "locale": "de" (cualquier etiqueta BCP 47); en /v1/send-form, usa el campo de formulario fm_locale. El locale de la respuesta es el idioma que se usó realmente; si la solicitud no lleva locale, se envía el idioma predeterminado.

Errores

Todos los errores tienen la misma forma:

{ "error": { "code": "origin_not_allowed", "message": "…", "docs_url": "https://docs.frontmail.dev/reference/errors/#origin-not-allowed", "details": {} } }

Estados posibles: 400, 401, 402 (solo en el modo reject), 403, 404, 409, 413, 422, 429, 451, 5xx. Cada código se explica en Códigos de error.

Límites

• Parámetros: 256 kB de JSON por mensaje; cadenas de 50 000 caracteres salvo que el esquema diga otra cosa.
• Lotes: 100 mensajes por solicitud.
• Adjuntos: según el plan, consulta Planes.
• Peticiones por segundo: según el plan, consulta Límites de solicitudes.