LinkedIn
Instagram
Facebook
WhatsApp
Telegram
Google Calendar
Calendario de Outlook
Únase a la comunidad SlackCorreo electrónico API de sincronización: Cómo funciona la sincronización del correo electrónico para productos SaaS
Crea funcionalidades SaaS que sincronicen bandejas de entrada de usuarios en tiempo real. Conecta Gmail, Outlook e IMAP a través de una única API de sincronización de correo electrónico, con webhooks, flujos OAuth y acceso completo a carpetas incluidos.
const UnipileClient = require('@unipile/node-sdk');
const client = new UnipileClient({
dsn: process.env.UNIPILE_DSN,
token: process.env.UNIPILE_TOKEN
});
// Obtener correos electrónicos sincronizados de la cuenta vinculada
const correos electrónicos = await cliente.email.listEmails({
account_id: 'acc_gmail_xyz',
carpeta: 'BANDEJA DE ENTRADA',
límite: 50
});
// Tiempo real: registrar webhook
await client.webhook.create({
url: 'https://tuapp.com/webhooks/email',
eventos: ['correo.nuevo', 'email.leer']
});
¿Qué es una API de sincronización de correo electrónico?
En API de sincronización de correo electrónico es una interfaz programática que permite que tu aplicación refleje continuamente el buzón de un usuario: leyendo nuevos mensajes, rastreando cambios de estado (leído/no leído, movido, eliminado) y reflejando la estructura de carpetas, sin que el usuario exporte datos manualmente. A diferencia de una API solo de envío, una API de sincronización de correo electrónico mantiene una réplica en vivo y bidireccional de la bandeja de entrada dentro de tu producto.
A nivel de protocolo, cada proveedor expone su propia primitiva de sincronización: Gmail utiliza historial.lista with a historialId cursor, Microsoft Graph utiliza consultas delta en el /mensajes/delta punto final, y los servidores IMAP estándar admiten el Ocioso comando para notificaciones push. A API de sincronización de correo electrónico unificada Unipile abstrae estos tres protocolos detrás de un solo punto final, por lo que su equipo escribe la lógica de sincronización una vez y la implementa en todos los proveedores.
Si estás construyendo un CRM, una herramienta de ventas, un asistente de correo electrónico con IA o cualquier SaaS que necesite datos de bandeja de entrada en tiempo real, una API de sincronización de correo electrónico es la base. Para el envío de correos electrónicos transaccionales (restablecimientos de contraseña, recibos), esa es una categoría diferente; consulta nuestra guía completa de API de correo electrónico o nuestro dedicado sincronización vs transaccional comparación.
Sincronización de correo electrónico vs. Envío de correo electrónico: por qué la distinción importa
Los desarrolladores a menudo confunden las API de sincronización de correo electrónico con las API de correo electrónico transaccional. Sirven para propósitos opuestos. Elegir la categoría incorrecta retrasa tu arquitectura semanas.
Lee y refleja el buzón de correo existente de un usuario en tu aplicación. Requiere que el usuario autorice el acceso a su cuenta (credenciales OAuth o IMAP). Tu aplicación se convierte en un lector secundario de su bandeja de entrada.
Usado por: CRMs, herramientas de participación de ventas, asistentes de correo electrónico con IA, centros de ayuda, archivado de correo electrónico, análisis de bandeja de entrada.
Envía correos electrónicos generados por el sistema desde tu propio dominio. No se necesita autorización del usuario. Te autenticas como el remitente (clave API), no como el usuario. Ejemplos: SendGrid, Mailgun, Resend, Amazon SES.
Unipile NO está en esta categoría. Unipile es el lado de sincronización, leyendo y duplicando las bandejas de entrada de los usuarios a través de OAuth.
¿Quién necesita una API de sincronización de correo electrónico?
Cualquier producto SaaS que necesite mostrar, analizar o actuar sobre el correo electrónico entrante de un usuario se basa en una API de sincronización de correo electrónico. Estos son los cinco casos de uso más comunes que vemos en producción.
Registra automáticamente cada correo electrónico entrante y saliente en el registro de contacto correcto. Los representantes de ventas dejan de copiar y pegar correos electrónicos; el CRM se convierte en el sistema de registro en tiempo real. No se requiere envío manual de BCC.
Guía de la API de correo electrónicoRealice un seguimiento de las tasas de respuesta, detecte las respuestas de ausencia y active secuencias de seguimiento basadas en eventos de la bandeja de entrada. Una API de sincronización de correo electrónico proporciona a sus secuencias conocimiento en tiempo real de lo que sucede en la bandeja de entrada del prospecto.
Enviar correo electrónico mediante programaciónAlimente un flujo de correo electrónico en vivo a un agente LLM que redacta respuestas, categoriza mensajes entrantes, extrae elementos de acción o enruta tickets. El agente necesita un flujo de sincronización continuo, no una exportación única. Es obligatorio un API de sincronización de correo electrónico en tiempo real.
Leer correos electrónicos programáticamenteConvierte correos electrónicos de clientes en tickets de soporte automáticamente, incluyendo todo el contexto del hilo y los archivos adjuntos. Sincroniza el estado del ticket de vuelta cuando el agente responde, para que la bandeja de entrada del cliente refleje el hilo de la resolución.
Comparar proveedores de API de correo electrónicoCapture cada correo electrónico entrante y saliente para cumplimiento, descubrimiento legal o análisis. Una API de sincronización de correo electrónico te permite crear un archivo consultable de todas las comunicaciones corporativas sin tocar directamente el servidor de correo.
Nivel gratuito de API de correo electrónicoAnaliza el volumen de correos electrónicos, los tiempos de respuesta, los patrones de conversación y el sentimiento en las cuentas vinculadas de un equipo. Los equipos de marketing, operaciones y finanzas utilizan análisis de bandeja de entrada para medir la calidad de la comunicación e identificar cuellos de botella.
Guía completa de la API de correo electrónicoCómo funciona la sincronización de correo electrónico: OAuth, Delta Sync y Webhooks
Una API de sincronización de correo electrónico es más que un punto de acceso de lectura. Es un canal con estado que autentica usuarios, mantiene la frescura de los tokens, rastrea el estado del buzón y entrega cambios en tiempo casi real. Esto es lo que sucede en cada capa.
El usuario hace clic en "Conectar tu bandeja de entrada" en tu aplicación. Se le redirige a la pantalla de consentimiento de Google o Microsoft, donde aprueba los ámbitos que solicita tu aplicación. Para Gmail, eso significa gmail.lectura o gmail.modificar; para Outlook significa Mail.Read o Mail.ReadWrite. Después de dar su consentimiento, tu aplicación recibe un token de acceso (válido por 1 hora para Google, 1 hora para Microsoft) y una token de actualización (de larga duración). Las cuentas IMAP utilizan nombre de usuario + contraseña o OAuth, dependiendo de la configuración del proveedor.
En la primera sincronización, la API de sincronización de correo electrónico realiza un respaldo completo: recupera la lista de carpetas (CONTENEDOR, Enviado, Borradores, etiquetas personalizadas) y recupera mensajes recientes hasta una profundidad configurable. Para Gmail, esto usa usuarios.mensajes.listar con paginación. Para Microsoft Graph, utiliza GET /yo/mensajes. Para IMAP, emite un SELECCIONAR BANDEJA DE ENTRADA seguido de un TRAER rango. La instantánea le da a su base de datos su estado de referencia, incluyendo los IDs de los mensajes y agrupaciones de hilos.
Después de la instantánea inicial, consultar repetidamente el buzón completo desperdiciaría cuota y ralentizaría tu aplicación. La sincronización Delta es la solución. Gmail ofrece una historialId cursor: tú llamas usuarios.historial.listar con el último conocido historialId y recibir solo los cambios (mensajes nuevos, cambios de etiquetas, eliminaciones) desde ese punto. Microsoft Graph utiliza GET /me/messages/delta with a $deltaToken. IMAP usa UID FETCH with a CAMBIADOSDESDE modificador (extensión CONDSTORE). sincronización delta El patrón mantiene las llamadas a la API al mínimo incluso para buzones de alto volumen.
Las tokens de acceso caducan. Tu infraestructura de sincronización de correo electrónico debe detectar 401 No autorizado respuestas, utilice el token de actualización para obtener un nuevo token de acceso de Google o Microsoft, y vuelva a intentar la solicitud fallida. Esto debe ocurrir de forma transparente, sin interrumpir la sesión del usuario. Los tokens de actualización en sí mismos pueden ser revocados (por el usuario, por una política de administrador o después de 6 meses de inactividad (Google)), por lo que su sistema debe detectar la revocación y solicitar al usuario que vuelva a autorizar.
La sondeo con un horario introduce latencia: un sondeo de 30 segundos significa que los correos electrónicos pueden tener hasta 30 segundos de antigüedad. Para funciones de bandeja de entrada en tiempo real, la API de sincronización de correo electrónico debe soportar notificaciones push. Gmail utiliza Google Cloud Pub/Sub: registras un tema y Gmail publica una notificación cada vez que historialId avances. Microsoft Graph utiliza notificaciones de cambio en /me/mailFolders/inbox/messages resource. Una API de sincronización de correo electrónico unificada (como Unipile) normaliza esto en un único evento de webhook - correo.nuevo entregado a tu punto final sin importar el proveedor.
APIs nativas de sincronización de correo electrónico: Gmail, Microsoft Graph e IMAP
Cada uno de los tres proveedores de correo electrónico expone una primitiva de sincronización diferente. Comprender las diferencias revela por qué construir una API de sincronización de correo electrónico multiproveedor desde cero lleva meses, no días.
Gmail - historial.listar + Pub/Sub
Cuentas de Google Workspace y personales
El modelo de sincronización de Gmail gira en torno a historialId cursor. Después de tu sincronización inicial, cada llamada subsiguiente a usuarios.historial.listar devuelve solo cambios desde tu último conocido historialId - mensajes nuevos, adiciones de etiquetas, eliminaciones de etiquetas y eliminaciones.
Para empuje en tiempo real, Gmail requiere que configures un tema de Google Cloud Pub/Sub y llames usuarios.ver para registrarlo. Gmail entonces publica una notificación (que contiene un nuevo historialIda tu tema cada vez que el buzón cambia. Tu trabajador se suscribe al tema y llama historial.lista para obtener los cambios reales.
Límites de tarifa: Mil millones de unidades de cuota por día por proyecto, con límites por usuario. usuarios.mensajes.obtener cuesta 5 unidades; usuarios.historial.listar cuesta 2 unidades. Para una aplicación multiinquilino, la gestión de cuotas se convierte en una preocupación a tiempo completo. Ver guía de API de correo electrónico para más.
from googleapiclient.discovery import construir
Sincronización Delta # mediante el cursor historyId
def obtener_cambios(servicio, historial_id)
resultado = service.usuarios().historial().list(
ID de usuario=yo,
inicioIdHistorial=id_historial,
tiposDeHistorial=[
'mensajeAñadido',
'mensajeEliminado',
'etiquetaAgregada'
]
).ejecutar()
return resultado.obtener('historia', [])
Outlook / Microsoft 365 - Consultas delta de Graph
Outlook Personal y Exchange Online / M365
Microsoft Graph usa consultas delta en el /yo/mensajes/delta punto final. La primera llamada devuelve una página completa de mensajes más un @odata.deltaLink. Las llamadas posteriores a ese delta link devuelven solo mensajes modificados desde la llamada anterior: elementos nuevos, modificados y eliminados.
Para empuje en tiempo real, Microsoft Graph admite notificaciones de cambios mediante webhooks. Usted registra una suscripción en /me/mailFolders/inbox/messages with a notificationUrl. Microsoft envía un POST a tu URL cuando los mensajes cambian. Las suscripciones deben renovarse cada 4230 minutos (aproximadamente 3 días) o caducarán.
Nota: Esto cubre tanto las cuentas personales de Outlook como Microsoft 365 / Exchange Online: utilizan la misma API de Graph. Vea Guía de integración de correo electrónico de Microsoft Graph para obtener detalles sobre el registro de aplicaciones y el consentimiento del administrador.
// Microsoft Graph sincronización delta
async function fetchDeltaMessages(cliente, deltaLink) {
const url = deltaLink
|| '/me/messages/delta';
const res = await client
.api(url)
.elegir('id,asunto,de,fechaHoraRecibido')
.consiga();
return {
mensajes: res.value,
nextDelta: res['@odata.deltaLink']
};
}
IMAP - Comando IDLE + UID FETCH
Respaldo universal para cualquier servidor de correo
IMAP (RFC 3501) es anterior a las API de sincronización modernas por décadas. Expone por carpeta números de secuencia y UIDs. Para la sincronización delta, el ALMACÉNCOND extensión (RFC 7162) añade un MODSEC valor a cada mensaje, permitiéndole recuperar solo mensajes con un MODSEC más alto que tu último valor conocido a través de UID FETCH * (FLAGS) (CHANGEDSINCE modseq).
Para empuje en tiempo real, IMAP admite la Ocioso (RFC 2177). Tu cliente envía Ocioso y el servidor empuja EXISTE o BORRAR respuestas cuando la carpeta cambia - no se necesita sondeo. La mayoría de los servidores IMAP admiten IDLE; las conexiones deben actualizarse cada 29 minutos para evitar tiempos de espera.
IMAP es crucial porque cubre cualquier servidor de correo no gestionado por Google o Microsoft: Exchange corporativo (local), ProtonMail, Zoho, Fastmail y dominios personalizados. Ver Guía de integración IMAP para un recorrido completo de implementación.
const Imap = require('imap');
const imap = new Imap{ host, puerto: 993, tls: true });
imap.una vez('listo', () => {
imap.abrir la caja('BANDEJA DE ENTRADA', true, () => {
imap.on('correo', (numNew) => {
Mensaje nuevo recibido en modo inactivo
traerNuevosMensajes(numNuevos);
});
});
});Cobertura de funciones de la API de correo electrónico por proveedor
Una sola integración de Unipile te da acceso a todas las operaciones de correo electrónico a través de proveedores de Gmail, Outlook e IMAP. Haz clic en el encabezado de cualquier proveedor para leer la guía de integración completa.
| Característica | Gmail | Outlook / M365 | IMAP / SMTP |
|---|---|---|---|
| Autenticación | |||
| OAuth2 (almacenamiento sin contraseña) | ✓ | ✓ | Contraseña de aplicación |
| Flujo de autenticación o consentimiento alojado | ✓ | ✓ | ✓ |
| Renovación automática de tokens | ✓ | ✓ | ✓ |
| Operaciones de correo electrónico | |||
| Enviar correo electrónico desde la cuenta de usuario | ✓ | ✓ | ✓ |
| Leer y listar correos electrónicos | ✓ | ✓ | ✓ |
| Enviar con archivos adjuntos | ✓ | ✓ | ✓ |
| Responder en el hilo existente | ✓ | ✓ | ✓ |
| Gestión de borradores | ✓ | ✓ | ✓ |
| Etiquetas / Carpetas | ✓Etiquetas | ✓Carpetas | ✓Carpetas |
| Límite diario de envío (aprox.) | ~500 / día | ~10.000 / día | Dependiente del servidor |
| Sincronización y Eventos | |||
| Ganchos web en tiempo real | ✓ | ✓ | ✓ |
| Sincronización delta incremental | ✓ | ✓ | ✓ |
| Agrupación de hilos | ✓ | ✓ | ✓ |
| SOC 2 Tipo II / CASA Nivel 2 | ✓ | ✓ | ✓ |
GmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPOmite el texto estándar de Gmail + Graph + IMAP. Una API de sincronización de correo electrónico cubre los tres.
La API unificada de sincronización de correo electrónico de Unipile se conecta a Gmail, Outlook e IMAP a través de un único punto de conexión. Flujos de OAuth, actualización de tokens, sincronización delta y webhooks: todo gestionado por usted. Empieza gratis, no se requiere tarjeta de crédito.
La complejidad oculta de la sincronización de correo electrónico a escala
Construir una API de prueba de concepto para sincronización de correo electrónico lleva un fin de semana. Construir una que sea confiable en producción con 1000 cuentas vinculadas lleva meses. Esto es lo que nadie te dice desde el principio.
Gmail aplica cuotas por usuario (250 unidades de cuota por segundo) y límites diarios por proyecto. Microsoft Graph limita a 10,000 solicitudes cada 10 minutos por aplicación. Con 500 cuentas enlazadas sincronizándose según lo programado, necesitas un limitador de velocidad distribuido con retroceso exponencial, jitter y aislamiento de cola por cuenta. Un único pico de una cuenta puede agotar la cuota para todas las demás.
Cada cuenta enlazada tiene un token de acceso que expira. Con 1000 cuentas, se pueden esperar docenas de actualizaciones de tokens concurrentes durante las ventanas de sincronización pico. Una sola actualización fallida genera un efecto dominó que resulta en ciclos de sincronización perdidos. Necesitas un servicio dedicado para el ciclo de vida de los tokens con lógica de reintentos, detección de revocación y un sistema de alertas para indicar a los usuarios que vuelvan a autorizar cuando los tokens de actualización expiren.
Gmail usa etiquetas (un mensaje puede tener varias etiquetas simultáneamente). Outlook usa carpetas (jerárquicas, con operaciones de mover). IMAP también usa carpetas pero con espacios de nombres que varían según el proveedor del servidor. Normalizarlos en un modelo de carpetas consistente para su aplicación requiere lógica de mapeo específica del proveedor. Los casos extremos incluyen buzones compartidos, acceso delegado y la distinción de Gmail entre "Todo el correo" e "Bandeja de entrada".
Los archivos adjuntos de correo electrónico pueden ser grandes. La obtención y el almacenamiento de archivos adjuntos para cada correo electrónico sincronizado en miles de cuentas se suman rápidamente tanto en costos de ancho de banda como de almacenamiento. Necesitas una canalización de transmisión que solo descargue archivos adjuntos bajo demanda, almacenamiento deduplicado y una capa de CDN para servirlos desde tu producto. El análisis MIME en sí introduce errores: los correos electrónicos de varias partes, la codificación quoted-printable y los archivos adjuntos en línea requieren un manejo específico.
hilos de Gmail por threadId - un concepto del lado del servidor. IMAP no tiene una organización nativa de hilos; reconstructas los hilos usando la Referencias y En respuesta a cabeceras (RFC 5322). Outlook tiene conversationId. Normalizar los hilos entre proveedores, especialmente para las respuestas entre proveedores, requiere heurísticas de respaldo basadas en la normalización del asunto y las cadenas de Message-ID.
Las notificaciones de Pub/Sub de Gmail no están garantizadas; los mensajes perdidos durante el tiempo de inactividad no se reenviarán. Las suscripciones de webhook de Microsoft Graph expiran y deben renovarse. Si su receptor de webhook está inactivo durante una notificación push, perderá el evento y deberá recurrir a la consulta. Una API de sincronización de correo electrónico de producción necesita un bucle de reconciliación que se ponga al día periódicamente con los eventos perdidos utilizando el cursor de sincronización delta, independientemente de la disponibilidad del webhook.
3 Arquitecturas de Sincronización de Correo Electrónico Comparadas
Los equipos que desarrollan funcionalidades de sincronización de correo electrónico suelen evaluar tres patrones de implementación. Aquí hay una comparación honesta de cada uno, desde el esfuerzo de desarrollo hasta el costo de mantenimiento continuo.
Sincroniza correos electrónicos con la API unificada de sincronización de correo electrónico de Unipile
La API de sincronización de correo electrónico de Unipile cubre Gmail, Outlook e IMAP a través de una interfaz unificada. Los flujos OAuth, la actualización de tokens, la sincronización delta y la entrega de webhooks son gestionados por usted; su equipo implementa la función, no la infraestructura.
Regístrate en dashboardv2.unipile.com/register. El nivel gratuito de la API de correo electrónico te da acceso a todos los proveedores sin necesidad de tarjeta de crédito. Obtienes tu DSN (Nombre de Origen de Datos) y tu token de API de inmediato.
Utilice el flujo OAuth hospedado de Unipile para permitir que su usuario autorice el acceso a su cuenta de Gmail o Outlook. Para IMAP, recopile sus credenciales y páselas a POST /cuentas. Unipile maneja la redirección OAuth, el intercambio de tokens y almacena el token de actualización de forma segura.
Llamar GET /correos electrónicos con el account_id de la cuenta vinculada. Unipile ejecuta la sincronización delta contra el Gmail de historial.lista, el punto de conexión delta de Microsoft Graph o IMAP ALMACÉNCOND - siempre obtienes la misma respuesta JSON normalizada independientemente del proveedor.
Publica la URL de tu endpoint en la API de webhooks de Unipile. Cuando llegue un nuevo correo electrónico a cualquier cuenta vinculada - ya sea Gmail, Outlook o IMAP - Unipile entregará una normalizada correo.nuevo evento a tu URL. Sin configuración de Pub/Sub, sin renovación de suscripción Graph, sin gestión de conexiones INACTIVAS. Ver guía de API de correo electrónico para referencia completa del evento.
Llamar GET /correos/{id} para recuperar el cuerpo completo del mensaje (HTML y texto plano), las cabeceras, las partes MIME y las referencias a los archivos adjuntos. Los archivos adjuntos se sirven a través de URL firmadas; nunca tendrá que almacenar datos MIME sin procesar usted mismo. Ver leer correos electrónicos programáticamente por ejemplo.
const axios = require('axios');
const DSN = process.env.UNIPILE_DSN;
const TOKEN = process.env.UNIPILE_TOKEN;
const api = axios.create({
urlBase: `https://${DSN}/api/v1`,
cabeceras: { 'X-API-KEY': TOKEN }
});
// Paso 3 - Listar correos sincronizados
async function listEmails(accountId) {
const { datos } = await api.consiga('/correos', {
params: {
account_id: account_id,
carpeta: 'BANDEJA DE ENTRADA',
límite: 20
}
});
return data.elementos;
}
// Paso 4 - Registrar webhook
async function registrarWebhook() {
await api.Correo electrónico:(/webhooks, {
url: 'https://yourapp.com/api/eventos-de-correo-electronico',
eventos: ['correo.nuevo', 'correo electrónico.actualizado']
});
}
// Paso 5 - Obtener contenido completo del correo electrónico
async function obtenerCorreoElectronico(emailId) {
const { datos } = await api.consiga(`/emails/${emailId}`);
return datos;
}Deja de reconstruir el mismo pipeline de sincronización de correo electrónico para cada proveedor.
Conecta Gmail, Outlook e IMAP a través de una única API de sincronización de correo electrónico. Webhooks en tiempo real, sincronización delta y gestión de tokens OAuth: todo se maneja. Tu equipo se centra en el producto, no en la infraestructura.
Sincronización de correo electrónico en tiempo real: Webhooks vs. Sondeo vs. IMAP IDLE
Elegir el mecanismo en tiempo real incorrecto para tu API de sincronización de correo electrónico añade latencia, consume cuota o deja tu aplicación ciega durante las interrupciones. Aquí hay una comparación directa de los tres enfoques.
| Acercamiento | Cómo funciona | Latencia | Mejor para | Complejidad |
|---|---|---|---|---|
| Webhooks (push) | El proveedor envía una solicitud POST HTTP a tu endpoint cuando un buzón cambia. Gmail usa Pub/Sub; Microsoft Graph usa notificaciones de cambio. | Menores de 5 años | Gmail, Outlook, APIs unificadas como Unipile | Mediano - gestión de suscripción requerida |
| Sondeo (programado) | Su trabajador llama a la API del proveedor según un horario (cada 30 s, 1 min, 5 min) y recupera los cambios utilizando un cursor delta. | Treinta segundos a cinco minutos | Todos los proveedores, configuraciones sencillas | Bajo - pero intensivo en cuotas a escala |
| IMAP IDLE (sondeo largo) | Tu cliente envía IDLE al servidor; el servidor envía notificaciones EXISTS cuando llega correo nuevo. Conexión mantenida abierta hasta 29 minutos. | Menores de 1 año | Solo servidores IMAP | Alta - una conexión TCP por buzón |
Recomendación de producción: Usa webhooks como tu principal mecanismo en tiempo real y ejecuta un fallback de sondeo delta-sync (cada 5 minutos) para capturar eventos perdidos durante el tiempo de inactividad. Con la API de sincronización de correo electrónico de Unipile, ambos se configuran una vez: el unificado correo.nuevo el webhook se activa independientemente de si la cuenta es Gmail, Outlook o IMAP, y un bucle de reconciliación en segundo plano maneja automáticamente los eventos omitidos.
Seguridad y Cumplimiento para APIs de Sincronización de Correo Electrónico
El acceso a las bandejas de entrada de los usuarios crea importantes obligaciones de seguridad y regulatorias. Esto es lo que su implementación de la API de sincronización de correo electrónico debe abordar antes de pasar a producción.
Solicite solo los ámbitos que su aplicación necesita. Para sincronización de correo electrónico de solo lectura, solicite gmail.lectura en vez de gmail.modificar. Para Microsoft Graph, solicite Mail.Read en vez de Mail.ReadWrite. La verificación CASA de Google (requerida para aplicaciones con más de 100 usuarios) revisa de cerca los alcances solicitados; la ampliación excesiva de los alcances retrasa la aprobación.
Los tokens de actualización de OAuth son credenciales de larga duración que otorgan acceso completo al buzón. Deben almacenarse cifrados en reposo (AES-256 como mínimo) y nunca registrarse. Rote periódicamente las claves de cifrado de sus tokens. El compromiso de un token de actualización es equivalente al compromiso de una contraseña para la cuenta de correo electrónico conectada.
El contenido de correo electrónico sincronizado de usuarios de la UE es un dato personal según el RGPD. Necesitas una base legal para el procesamiento (típicamente el consentimiento explícito del usuario a través de OAuth), un acuerdo de procesamiento de datos con tu proveedor de API de sincronización de correo electrónico y una política clara de retención de datos. Si tu infraestructura tiene sede en EE. UU., asegúrate de tener Cláusulas Contractuales Tipo (SCC) o un mecanismo de transferencia equivalente para los datos de la UE.
Cualquier aplicación que utilice ámbitos OAuth de Gmail con más de 100 usuarios debe completar el CASA (Evaluación de seguridad de aplicaciones en la nube). Esta es una revisión de seguridad de tu aplicación, que incluye el código, la infraestructura y la justificación del alcance de OAuth. El proceso dura de 4 a 8 semanas. Empieza cuanto antes: suspender la CASA significa perder el acceso a Gmail para todos los usuarios hasta que la apruebes.
Siempre verifica la firma en las cargas útiles de webhook entrantes de tu API de sincronización de correo electrónico. Un webhook sin firmar o verificado incorrectamente puede ser falsificado para inyectar eventos de correo electrónico falsos en tu aplicación. Unipile firma todas las entregas de webhook con HMAC-SHA256. Verifica la X-Unipile-Firma encabezado antes de procesar cualquier evento.
Registre cada acción que su aplicación realiza en los datos de correo electrónico sincronizados: quién accedió a qué mensajes, cuándo y qué se hizo con los datos. Los registros de auditoría son necesarios para el cumplimiento de SOC 2 Tipo II y a menudo son lo primero que los clientes empresariales solicitan durante las revisiones de seguridad. Conserve los registros durante un mínimo de 90 días, idealmente 1 año.
Errores comunes al crear una API de sincronización de correo electrónico
Estos son los errores y fallos de arquitectura que vemos con más frecuencia en las implementaciones de API de sincronización de correo electrónico. Todos ellos son prevenibles con las decisiones de diseño correctas desde el principio.
Cuando un token de actualización expira o es revocado, una implementación ingenua genera un error y detiene la sincronización, de forma silenciosa. El usuario no se entera de que su bandeja de entrada dejó de sincronizarse hasta que nota datos desactualizados. Corregir: implementar una capa de detección de revocaciones que capture concesión_inválida errores, marca la cuenta enlazada como que requiere una nueva autorización y notifica al usuario a través del sistema de notificaciones de tu producto.
Consultar cada 10 segundos en 200 cuentas vinculadas agota la cuota por proyecto de Gmail en cuestión de horas. Microsoft Graph empieza a devolver 429 Demasiadas solicitudes. El resultado son fallos de sincronización silenciosos para todas las cuentas, no solo para las que activaron la limitación. Corregir: utilizar webhooks como su mecanismo principal con una recuperación por sondeo de 5 minutos, e implementar límites de tasa por cuenta con retroceso exponencial en todos 429 respuestas.
El MIME sin procesar es grande, difícil de consultar y costoso de analizar al leer. Un solo correo electrónico con archivos adjuntos puede ocupar cientos de kilobytes. Corregir: Analiza el formato MIME durante la importación: extrae por separado el cuerpo HTML, el texto sin formato (como alternativa), los encabezados y los metadatos de los archivos adjuntos. Almacena los archivos binarios adjuntos en un almacenamiento de objetos (S3 o equivalente), no en tu base de datos principal. Solo con esto, reducirás los costes de almacenamiento entre un 60 % y un 80 % para los buzones de correo corporativos habituales.
Gmail threadId funciona solo dentro de Gmail. Si tu aplicación muestra un hilo que abarca una cuenta de Gmail y una cuenta de Outlook (por ejemplo, una respuesta enviada desde un buzón diferente), los identificadores de hilo nativos son inútiles. Corregir: construir un motor de subprocesamiento multiplataforma basado en ID-Mensaje, En respuesta ay Referencias encabezados. Normalizar las líneas de asunto (eliminar prefijos Re:/Fwd:) como recurso de respaldo para correos electrónicos que carezcan de estos encabezados.
La sincronización Delta se basa en un cursor almacenado: el de Gmail. historialId, de Microsoft Graph deltaLink, IMAP MODSEC. Si tu trabajador de sincronización se reinicia y el cursor solo se almacena en memoria, pierdes tu posición en el flujo de cambios. La próxima sincronización comenzará desde cero, duplicando todos los mensajes históricos o perdiendo la brecha. Corregir: persiste el cursor en tu base de datos después de cada ciclo de sincronización exitoso, atómicamente con el último lote de cambios procesados.
Para casos de uso de CRM, necesitas tanto correos electrónicos entrantes (recibidos) como salientes (enviados) para construir una línea de tiempo completa de comunicación. La etiqueta Bandeja de entrada de Gmail solo cubre el correo recibido; también necesitas ENVIADO. Microsoft Graph requiere consultar el Elementos enviados carpeta por separado. IMAP requiere seleccionar la Enviado carpeta explícitamente. Corregir: Sincroniza todas las carpetas relevantes al configurar la cuenta, no solo la BANDEJA DE ENTRADA, y mapea los nombres de carpetas específicos del proveedor a tipos normalizados en tu modelo de datos.
Preguntas frecuentes sobre las API de sincronización de correo electrónico
Las preguntas más comunes que hacen los desarrolladores al implementar una API de sincronización de correo electrónico por primera vez.
historialId cursor con el usuarios.historial.listar endpoint. Microsoft Graph usa un deltaLink devuelto por el /mensajes/delta endpoint. IMAP utiliza el MODSEC valor de la extensión CONDSTORE. Una API unificada de sincronización de correo electrónico normaliza estos tres mecanismos diferentes detrás de una interfaz coherente.GET /correos electrónicos con el account_id recuperar mensajes sincronizados y registrar un punto final de webhook para recibir en tiempo real correo.nuevo eventos. Unipile maneja OAuth, actualización de tokens, sincronización delta y entrega de webhooks automáticamente.gmail.lectura. Si necesitas marcar mensajes como leídos o moverlos, solicita gmail.modificar. Para Microsoft Graph, solicite Mail.Read para acceso de solo lectura o Mail.ReadWrite para acceso completo. Solicite siempre los ámbitos mínimos que su aplicación realmente necesita. La verificación CASA de Google (requerida para aplicaciones con más de 100 usuarios) revisa de cerca la justificación de los ámbitos, y un exceso de ámbitos puede retrasar su aprobación.401 No autorizado respuestas, utiliza el token de actualización almacenado para obtener un nuevo token de acceso y reintenta la solicitud fallida de forma transparente. Los propios tokens de actualización pueden ser revocados. Cuando se detecta la revocaciónconcesión_inválida error), marque la cuenta como que necesita una nueva autorización y notifique al usuario. Unipile gestiona automáticamente todo el ciclo de vida de los tokens para las cuentas vinculadas.EXISTE notificaciones cuando llegan nuevos mensajes. Esto permite una sincronización de la bandeja de entrada casi en tiempo real (latencia inferior a 1 segundo) sin sondeos constantes. Las conexiones IDLE deben actualizarse cada 29 minutos para evitar tiempos de espera del servidor. IDLE funciona con cualquier servidor IMAP que lo admita, lo que incluye la mayoría de los servidores de correo modernos, como Exchange corporativo, Gmail a través de IMAP y Outlook a través de IMAP.