API de email explicada: cómo funciona, con ejemplos de código | Bitelio
Qué es una API de email y por qué la usan los desarrolladores: cómo fluyen las solicitudes, ejemplos funcionales en Node.js, Python, PHP, Ruby y Go, buenas prácticas y cómo elegir un proveedor.
Una API de email le da a tu aplicación la capacidad de enviar, recibir y gestionar correo electrónico mediante código. Desde restablecimientos de contraseña y confirmaciones de pedido hasta campañas de marketing completas, es la forma estándar de convertir el email en una parte fiable y escalable de tu software, en lugar de un añadido frágil.
En esta guía encontrarás el panorama completo: la mecánica que hay detrás de las API de email, código listo para ejecutar en cinco lenguajes, buenas prácticas contrastadas y un marco para elegir el proveedor adecuado.
¿Qué es una API de email?
Una API de email es una interfaz HTTP para enviar y gestionar correo electrónico, sin necesidad de configurar servidores SMTP a mano. El proveedor absorbe toda la mecánica de entrega detrás de endpoints limpios: una sola solicitud envía el mensaje, y los webhooks informan de lo que le sucede después.
SMTP (tradicional)
- • El protocolo básico para transmitir correo
- • La gestión de la conexión recae en ti
- • El manejo de errores también es cosa tuya
- • Poca visibilidad sobre el resultado de la entrega
- • Notablemente más difícil de implementar
- • Puerto 25, 587 o 465
API de email (moderna)
- • Interfaz RESTful sobre HTTP
- • Sin gestión de conexiones
- • Los errores llegan como respuestas estructuradas
- • Seguimiento y analítica listos para usar
- • Mucho más rápida de integrar
- • HTTP/HTTPS estándar
Cuándo usar una API de email
Los mensajes transaccionales (restablecimientos de contraseña, confirmaciones de pedido), las notificaciones automatizadas y las campañas gestionadas por código son exactamente para lo que se crearon las API de email. Siempre que sea el software quien pulsa «enviar», una API supera al SMTP en bruto en casi cualquier escenario.
Cómo funcionan las API de email
1. Autenticación
Cada solicitud lleva una clave de API, normalmente en una cabecera, que le indica al servicio quién eres y confirma que tienes permiso para acceder.
2. Realiza la solicitud HTTP
Envías una solicitud POST con un payload JSON al endpoint que contiene todo sobre el mensaje: destinatario, asunto, cuerpo y cualquier extra.
3. La API valida y encola
El servicio comprueba el payload, coloca el mensaje en su cola de entrega y devuelve una respuesta con el ID del email y su estado actual.
4. Entrega del email
A partir de ahí, el proveedor se encarga de todo: negocia las conexiones SMTP, reintenta los fallos y hace llegar el mensaje al servidor de correo del destinatario.
5. Webhooks y seguimiento
Los eventos de entrega (entregado, rebotado, abierto, clicado) te llegan en forma de llamadas webhook, y la API te permite consultar el estado de cualquier email cuando lo necesites.
Ejemplos de código de la API de email
Los siguientes fragmentos muestran un envío con la API de Bitelio en cinco lenguajes populares:
JavaScript / Node.js
// Using fetch (Node.js 18+ or with node-fetch)
const response = await fetch('https://api.bitelio.com/v1/send', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
},
body: JSON.stringify({
to: 'user@example.com',
subject: 'Welcome to our platform!',
body: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
// Optional fields
from: 'noreply@yourdomain.com',
name: 'Your Company',
replyTo: 'support@yourdomain.com'
})
});
const data = await response.json();
if (response.ok) {
console.log('Email sent!', data.emailId);
} else {
console.error('Failed to send:', data.error);
}Python
import requests
response = requests.post(
'https://api.bitelio.com/v1/send',
headers={
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
},
json={
'to': 'user@example.com',
'subject': 'Welcome to our platform!',
'body': '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
'from': 'noreply@yourdomain.com',
'name': 'Your Company'
}
)
if response.status_code == 200:
data = response.json()
print(f"Email sent! ID: {data['emailId']}")
else:
print(f"Error: {response.json()['error']}")PHP
<?php
$ch = curl_init('https://api.bitelio.com/v1/send');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer YOUR_API_KEY'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'to' => 'user@example.com',
'subject' => 'Welcome to our platform!',
'body' => '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
'from' => 'noreply@yourdomain.com',
'name' => 'Your Company'
]));
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode($response, true);
if ($httpCode === 200) {
echo "Email sent! ID: " . $data['emailId'];
} else {
echo "Error: " . $data['error'];
}
?>Ruby
require 'net/http'
require 'json'
uri = URI('https://api.bitelio.com/v1/send')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.path)
request['Content-Type'] = 'application/json'
request['Authorization'] = 'Bearer YOUR_API_KEY'
request.body = {
to: 'user@example.com',
subject: 'Welcome to our platform!',
body: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
from: 'noreply@yourdomain.com',
name: 'Your Company'
}.to_json
response = http.request(request)
data = JSON.parse(response.body)
if response.code.to_i == 200
puts "Email sent! ID: #{data['emailId']}"
else
puts "Error: #{data['error']}"
endGo
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
type EmailRequest struct {
To string `json:"to"`
Subject string `json:"subject"`
Body string `json:"body"`
From string `json:"from"`
Name string `json:"name"`
}
func main() {
email := EmailRequest{
To: "user@example.com",
Subject: "Welcome to our platform!",
Body: "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
From: "noreply@yourdomain.com",
Name: "Your Company",
}
jsonData, _ := json.Marshal(email)
req, _ := http.NewRequest("POST", "https://api.bitelio.com/v1/send", bytes.NewBuffer(jsonData))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error:", err)
return
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
if resp.StatusCode == 200 {
var result map[string]interface{}
json.Unmarshal(body, &result)
fmt.Printf("Email sent! ID: %v\n", result["emailId"])
} else {
fmt.Println("Error:", string(body))
}
}Funcionalidades habituales de una API de email
Funcionalidades de envío
- • Envíos puntuales y envíos por lotes
- • Cuerpos en HTML y en texto plano
- • Archivos adjuntos
- • Compatibilidad con CC y CCO
- • Inyección de cabeceras personalizadas
- • Renderizado de plantillas en el servidor
- • Programación de envíos
Seguimiento y analítica
- • Estado de entrega por mensaje
- • Seguimiento de aperturas
- • Seguimiento de clics
- • Detección automática de rebotes
- • Visibilidad de quejas de spam
- • Gestión de bajas
- • Paneles de analítica en tiempo real
Webhooks y eventos
- • Confirmaciones de entrega
- • Notificaciones de rebote
- • Alertas de quejas
- • Notificaciones de baja
- • Flujos de eventos de apertura y clic
- • Disparadores de eventos definidos por el usuario
Funcionalidades de gestión
- • Controles de listas de supresión
- • Administración de contactos
- • Herramientas de verificación de dominio
- • Bibliotecas de plantillas
- • Gestión del ciclo de vida de las claves de API
- • Límite de frecuencia
Buenas prácticas para una API de email
Protege tus claves de API
Las claves deben vivir en variables de entorno, nunca en el código fuente. Mantén claves distintas para cada entorno (desarrollo, staging, producción), rótalas con regularidad y revócalas de inmediato ante cualquier indicio de exposición.
Implementa un manejo de errores adecuado
Cada clase de estado HTTP merece su propia respuesta:
- 200: Éxito
- 400-499: Problemas del lado del cliente (solicitud mal formada, validación fallida) - reintentar no sirve de nada
- 500-599: Fallos del lado del servidor - reintenta usando backoff exponencial
- 429: Has superado el límite de frecuencia - haz una pausa y vuelve a intentarlo más tarde
Usa webhooks para el estado de entrega
Olvídate del bucle de sondeo (polling). Registra webhooks y deja que los eventos de entrega (entregado, rebotado, abierto, clicado) lleguen a ti en tiempo real: menos carga en ambos lados y la información llega antes.
Respeta los límites de frecuencia
Incorpora tu propio control de frecuencia en el código en lugar de chocar contra el límite del proveedor. Encola el correo saliente, envíalo por lotes y trata cualquier 429 como una señal para reducir la frecuencia de forma exponencial.
Valida las direcciones de email
Comprueba el formato de la dirección antes de que la solicitud salga de tu aplicación, y vigila los errores tipográficos clásicos. Cuando lo que está en juego es más importante, una API de validación dedicada puede confirmar la entregabilidad de antemano.
Usa plantillas
Mantén las plantillas de email del lado del proveedor en lugar de incrustar HTML en tu base de código. Así, el equipo de marketing y soporte puede ajustar los textos sin esperar a un despliegue.
Monitoriza las métricas de entregabilidad
Vigila de forma continua las tasas de rebote, las tasas de quejas y el engagement, con alertas configuradas para cualquier anomalía. Detectar a tiempo un deterioro en la entregabilidad siempre sale más barato que solucionarlo tarde.
Prueba en modo sandbox o desarrollo
Desarrolla contra el modo sandbox o de pruebas, y ensaya los caminos problemáticos (respuestas de error, comportamiento de reintento, procesamiento de webhooks) mucho antes de que nada llegue a producción.
Registra las solicitudes y respuestas de la API
Registra cada intercambio con la API, excepto los secretos como las claves de API. Esos registros resultan muy valiosos a la hora de depurar un misterio de entrega o analizar tus patrones de envío.
Gestiona los timeouts
Asigna un timeout razonable a cada llamada a la API (lo habitual son 10-30 segundos) y nunca hagas esperar a un usuario final por el proveedor de email. Envía los correos a una cola asíncrona siempre que la latencia importe.
Cómo elegir un proveedor de API de email
A la hora de elegir un proveedor, valora tus opciones con estos criterios:
Reputación de entregabilidad
Prioriza proveedores cuya infraestructura tenga un historial probado de llegada a la bandeja de entrada. Una API de email que entrega habitualmente en spam no te está ahorrando nada.
Conjunto de funcionalidades
Ajusta las capacidades a tus necesidades: plantillas, webhooks, analítica, programación, adjuntos, etc. Ten en cuenta que algunos servicios están orientados sobre todo a lo transaccional, mientras que otros se inclinan más hacia el marketing.
Modelo de precios
Lee con atención la página de precios: tarifas por mensaje, estructuras por niveles, cargos por excedente. Calcula el coste con tu volumen previsto y mantente alerta ante comisiones ocultas o saltos de precio bruscos a medida que creces.
Experiencia de desarrollador
Una documentación completa, un SDK para tu stack, mensajes de error que realmente se explican por sí solos y un soporte que responde: todo esto se traduce en semanas de tiempo de integración ahorrado.
Escalabilidad y fiabilidad
Hazte las preguntas difíciles: ¿absorberán tus picos de tráfico? ¿Qué SLA se comprometen a cumplir? ¿Hay redundancia y failover reales detrás de la API?
Cumplimiento y seguridad
Confirma que el proveedor cumple con el RGPD, la CAN-SPAM y cualquier otra normativa que rija tu mercado, y busca certificaciones de seguridad reconocidas como SOC 2 o ISO 27001.