Guía de API de correo electrónico para desarrolladores: Sincronización, OAuth y código (2026)

Integración de API de correo electrónico: De OAuth a sincronización en tiempo real

Una integración real de una API de correo electrónico sigue cuatro fases independientemente del proveedor al que te dirijas. Lee esta sección como una lista de verificación antes de comenzar tu implementación: omitir cualquier paso aquí es la razón más común por la que las integraciones funcionan en desarrollo y fallan en producción.

Autenticación OAuth 2.0

Tanto Gmail como Microsoft Graph utilizan el estándar Flujo de código de autorización OAuth 2.0. Los mecanismos son idénticos: redirige al usuario al proveedor, recibe un código único en tu URL de devolución de llamada, canjéalo por un token de actualización de larga duración en el lado del servidor, luego usa ese token de actualización para generar tokens de acceso de corta duración para cada llamada posterior a la API.

• Redirige al usuario al punto final de autorización del proveedor con tu client_id, uri_redireccionamiento, y lo solicitado alcance.
• El usuario otorga los permisos, el proveedor redirige a tu URL de devolución de llamada con una clave de un solo uso código parámetro.
• Tu servidor intercambia esas código para un token_de_acceso (esperanza de vida de 1 hora) y un token de actualización a través de un canal secundario POST.
• Guarde el token de actualización seguro en el lado del servidor, cifrado en reposo. Esta es la credencial de larga duración que utilizas para generar nuevos tokens de acceso automáticamente.

Nota específica de Gmail: Gmail no soporta la autenticación simple por clave API para el acceso al buzón; se requiere OAuth 2.0. Para una comparación detallada, consulta ¿Puedo usar una clave API con Gmail?

Enviar y recibir correos electrónicos

Una vez autenticado, las dos siguientes operaciones cubren el 80% del uso típico de la API de correo electrónico: recuperando la bandeja de entrada y enviando un mensaje. Con la API unificada de Unipile, ambos funcionan de manera idéntica en Gmail, Outlook e IMAP a través de un único conjunto de puntos finales.

# Obtener los últimos 50 correos electrónicos de una bandeja de entrada conectada
curl --request GET \
  --url 'https://api.unipile.com/api/v1/emails?limit=50&folder=inbox' \
  --header 'X-API-KEY: TU_API_KEY'

# Enviar un correo electrónico de texto plano
curl --request POST \
  --url 'https://api.unipile.com/api/v1/emails' \
  --header 'X-API-KEY: TU_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "account_id": "TU_ACCOUNT_ID",
    "subject": "Hola desde Unipile",
    "body": "Hola, este es un correo electrónico de texto plano",
    "to": [{"display_name":"John Doe","identifier":"john@example.com"}]
  }'

Unipile también soporta las características avanzadas de envío típicas que los desarrolladores esperan: archivos adjuntos (formulario de varias partes con varios archivos), encabezados personalizados pasando arreglos de X- cabeceras prefijadas), responder-en-hilo (usando el mensaje original proveedor_id), reemplazo de nombre de visualización, alias de remitente permitido, y seguimiento de aperturas / enlace con eventos de webhook en tiempo real. Cada uno de estos se mapea a un único campo en el cuerpo de la solicitud, sin necesidad de negociación de protocolo.

# Enviar con adjuntos + encabezados personalizados + seguimiento
curl --request POST \
  --url 'https://api.unipile.com/api/v1/emails' \
  --header 'X-API-KEY: TU_API_KEY' \
  --form 'account_id=TU_ACCOUNT_ID' \
  --form 'subject=Borrador de contrato' \
  --form 'body=Por favor, encuentra el v3 adjunto.' \
  --form 'to=[{"identifier":"sarah@acme.com"}]' \
  --form 'attachments=@/ruta/a/contrato.pdf' \
  --form 'attachments=@/ruta/a/apendice.png' \
  --form 'custom_headers=[{"name":"X-Campaign-ID","value":"q1-outreach"}]' \
  --form 'tracking_options={"opens":true,"links":true,"label":"q1-outreach"}'

Para una referencia completa para desarrolladores que cubra todas las opciones de envío y el comportamiento específico del proveedor, consulte nuestro Guía de la API para enviar correos electrónicos.

Sincronización de correo electrónico en tiempo real

La sincronización de la bandeja de entrada es la parte más compleja de cualquier integración de correo electrónico y la que con mayor frecuencia se malinterpreta. Un robusto sincronización de correo electrónico la implementación tiene tres fases distintas: sincronización inicial, sincronización incremental y notificaciones de webhook en tiempo real. Omitir cualquiera de ellos produce una integración que funciona desde el primer día y falla a escala.

Planifique las renovaciones desde el primer día: las suscripciones de observación de Gmail Pub/Sub caducan después de 7 días y deben renovarse. Las suscripciones de Microsoft Graph en recursos de correo caducan después de un máximo de aproximadamente 3 días. Incorpore la renovación de suscripciones en su infraestructura de trabajos en segundo plano. antes yendo a producción, de lo contrario, tu integración dejará de recibir eventos silenciosamente.

Webhooks y eventos

Los webhooks son la forma en que una API de correo electrónico moderna le dice a su backend que algo sucedió, en tiempo real, sin que usted tenga que preguntar. En lugar de sondear /mensajes cada 30 segundos (costoso y lento), te suscribes una vez y el proveedor envía un payload JSON a tu endpoint cada vez que llega un nuevo correo electrónico, se lee, se responde o se elimina.

Los eventos a los que normalmente te suscribes son correo_recibido (un nuevo mensaje llegó a la bandeja de entrada), correo_enviado (un mensaje saliente se entregó con éxito), correo_abierto (el destinatario lo abrió, si el seguimiento está activado), enlace_correo_clic (el destinatario hizo clic en un enlace rastreado), y estado_de_cuenta (el buzón conectado necesita reautenticación, por ejemplo, después de un cambio de contraseña). Cada evento lleva suficiente contexto para que sus sistemas posteriores reaccionen sin realizar llamadas de API adicionales.