Referencia de API¶

La API de Email Transaccional de InteSys (impulsada por FrontEngine) es una API basada en HTTP JSON con endpoints al estilo RPC. Cada acción tiene su propio endpoint. Todas las solicitudes utilizan HTTPS con el método POST y parámetros codificados en JSON.

URL base: https://app1.frontengine.net

Autenticación¶

Todas las solicitudes de API requieren el encabezado X-Server-API-Key con su clave de API de servidor.

X-Server-API-Key: your-api-key-here

Obtenga su clave de API desde el portal del cliente de InteSys o contacte con soporte.

Mantenga su clave de API en secreto

Nunca exponga su clave de API en código del lado del cliente, repositorios públicos o registros. Rote las claves de inmediato si se ven comprometidas.

Errores de autenticación¶

Error	Descripción
`InvalidServerAPIKey`	El token proporcionado es inválido. La respuesta incluye el valor de `token` rechazado.
`ServerSuspended`	El servidor de correo asociado con sus credenciales ha sido suspendido.

Formato de respuesta¶

Todas las respuestas de la API siguen esta estructura:

{
  "status": "success",
  "time": 0.23,
  "flags": {},
  "data": {}
}

Campo	Tipo	Descripción
`status`	string	`success`, `parameter-error` o `error`
`time`	float	Tiempo de procesamiento del lado del servidor en segundos
`flags`	object	Metadatos adicionales (paginación, etc.)
`data`	object	Payload de respuesta o detalles del error

Códigos de estado HTTP¶

Código	Significado
`200`	Solicitud procesada (compruebe el campo `status` para el resultado)
`301` / `308`	Redirección (generalmente de http a https)
`500`	Error inesperado del servidor
`503`	Servicio no disponible (mantenimiento)

API de Envío¶

Enviar Mensaje¶

Envíe un email transaccional con control total sobre encabezados, cuerpo y archivos adjuntos.

POST /api/v1/send/message

Parámetros:

Parámetro	Tipo	Requerido	Descripción
`to`	array	Sí	Direcciones de email de destinatarios (máx. 50)
`cc`	array	No	Direcciones de copia (máx. 50)
`bcc`	array	No	Direcciones de copia oculta (máx. 50)
`from`	string	Sí	Dirección de email del remitente (debe ser de dominio verificado)
`sender`	string	No	Encabezado del remitente (si es distinto de `from`)
`subject`	string	Sí	Línea de asunto del email
`tag`	string	No	Etiqueta de clasificación para filtrado en analíticas
`reply_to`	string	No	Dirección de respuesta
`plain_body`	string	No*	Contenido del email en texto sin formato
`html_body`	string	No*	Contenido del email con formato HTML
`attachments`	array	No	Archivos adjuntos (véase a continuación)
`headers`	object	No	Encabezados personalizados del email
`bounce`	boolean	No	Si este mensaje es una respuesta de rebote

*Debe proporcionarse al menos uno de html_body o plain_body.

Objeto de adjunto:

Campo	Tipo	Descripción
`name`	string	Nombre de archivo (p. ej., `invoice.pdf`)
`content_type`	string	Tipo MIME (p. ej., `application/pdf`)
`data`	string	Contenido del archivo codificado en Base64

Códigos de error:

Error	Descripción
`ValidationError`	Fallo general de validación de parámetros
`NoRecipients`	No se proporcionaron direcciones de destinatarios
`NoContent`	No se proporcionó ni `html_body` ni `plain_body`
`TooManyToAddresses`	Más de 50 direcciones `to`
`TooManyCCAddresses`	Más de 50 direcciones `cc`
`TooManyBCCAddresses`	Más de 50 direcciones `bcc`
`FromAddressMissing`	No se especificó dirección `from`
`UnauthenticatedFromAddress`	Dominio de envío no verificado para este servidor
`AttachmentMissingName`	Adjunto proporcionado sin nombre de archivo
`AttachmentMissingData`	Adjunto proporcionado sin datos

Ejemplo: curl¶

curl -X POST https://app1.frontengine.net/api/v1/send/message \
  -H "X-Server-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Order Confirmation #12345",
    "html_body": "<h1>Thank you for your order!</h1><p>Order #12345 has been confirmed.</p>",
    "plain_body": "Thank you for your order! Order #12345 has been confirmed.",
    "tag": "order-confirmation",
    "reply_to": "[email protected]"
  }'

Ejemplo: Python¶

import requests

response = requests.post(
    "https://app1.frontengine.net/api/v1/send/message",
    headers={
        "X-Server-API-Key": "your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "from": "[email protected]",
        "to": ["[email protected]"],
        "subject": "Welcome!",
        "html_body": "<h1>Welcome to our platform!</h1>",
    },
)

print(response.json())

Ejemplo: Node.js¶

const response = await fetch(
  "https://app1.frontengine.net/api/v1/send/message",
  {
    method: "POST",
    headers: {
      "X-Server-API-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      from: "[email protected]",
      to: ["[email protected]"],
      subject: "Welcome!",
      html_body: "<h1>Welcome to our platform!</h1>",
    }),
  }
);

const data = await response.json();
console.log(data);

Enviar Raw (RFC2822)¶

Envíe un mensaje preformateado RFC2822. Útil para aplicaciones que construyen sus propios mensajes MIME.

POST /api/v1/send/raw

Parámetros:

Parámetro	Tipo	Requerido	Descripción
`mail_from`	string	Sí	Dirección del remitente del envelope
`rcpt_to`	array	Sí	Direcciones de destinatarios para la entrega
`data`	string	Sí	Mensaje RFC2822 codificado en Base64
`bounce`	boolean	No	Si este es una respuesta de rebote

Códigos de error:

Error	Descripción
`UnauthenticatedFromAddress`	Dominio del remitente no verificado para este servidor

API de Mensajes¶

Obtener Detalles del Mensaje¶

Recupere todos los detalles sobre un mensaje enviado.

POST /api/v1/messages/message

Parámetros:

Parámetro	Tipo	Requerido	Descripción
`id`	integer	Sí	El ID del mensaje
`_expansions`	array/boolean	No	Solicitar campos de datos adicionales. Pase `true` para todas las expansiones o un arreglo con los nombres de las expansiones.

Códigos de error:

Error	Descripción
`MessageNotFound`	No se encontró ningún mensaje con el ID proporcionado

Obtener Intentos de Entrega¶

Recupere todos los intentos de entrega para un mensaje específico.

POST /api/v1/messages/deliveries

Parámetros:

Parámetro	Tipo	Requerido	Descripción
`id`	integer	Sí	El ID del mensaje

Códigos de error:

Error	Descripción
`MessageNotFound`	No se encontró ningún mensaje con el ID proporcionado

Próximos pasos¶

Autenticación — Configure SPF, DKIM y DMARC para su dominio de envío
Webhooks — Reciba notificaciones de eventos de entrega en tiempo real