Construir

Cómo leer correos electrónicos a través de API: una guía para desarrolladores para acceder a la bandeja de entrada (2026)

Índice
Ojea las secciones
Guía para Desarrolladores 2026

Cómo leer correos electrónicos a través de API: Una guía para desarrolladores Acceso a la bandeja de entrada

Ámbito: Esta guía cubre sincronizar APIs para leer las bandejas de entrada existentes de los usuarios: API de Gmail, Microsoft Graph, IMAP y capas unificadas como Unipile. Esto es distinto de los servicios transaccionales (SendGrid, Mailgun) que envían correos electrónicos salientes desde tu dominio.

Crea productos que lean correos electrónicos de usuarios mediante programación. De una sola GET /api/v1/emails llamadas a webhooks en tiempo real, esta guía cubre todos los enfoques con código de trabajo en Node.js, Python y cURL.

Empezar prueba gratis Guía de la API de correo electrónico
leer_bandeja_entrada.js
// Lee correos electrónicos con una única llamada API unificada const response = await fetch( 'https://api3.unipile.com:PORT/api/v1/correos', { cabeceras: { 'X-API-KEY': process.env.UNIPILE_API_KEY, 'id_cuenta': accountId } } ); const { correos electrónicos } = await respuesta.json(); // Misma forma JSON para Gmail, Outlook y IMAP correos electrónicos.para cada uno(correo => { consola.log(asuntoCorreo.asunto, asistenteRemitente.asunto); });
200 OK - 47 correos devueltos (Gmail + Outlook + IMAP)
Funciona con: Gmail Outlook IMAP Gmail, Outlook y IMAP
Definición

¿Qué es una API de lectura de correo electrónico?

Una API para leer correos electrónicos es una interfaz HTTP que permite a tu aplicación acceder, recuperar y procesar correos electrónicos del buzón existente de un usuario, sin almacenar contraseñas ni crear integraciones específicas del proveedor. Es la base de cualquier producto que necesite visibilidad de la bandeja de entrada: sincronización de CRM, copilotos de IA para correo electrónico, automatización de soporte o archivado de cumplimiento.

Definición rápida

A leer correo electrónico API expone puntos finales para autenticarse contra el buzón de un usuario (a través de credenciales OAuth 2.0 o IMAP), listar mensajes de la bandeja de entrada, recuperar cuerpos completos de correos electrónicos con archivos adjuntos y suscribirse a eventos de entrega en tiempo real. Opera en la cuenta existente de Gmail, Outlook o IMAP del usuario - no un dominio que controlas. Esto lo diferencia de las API de correo transaccional (SendGrid, Mailgun, Resend), que envían correos electrónicos salientes en nombre de tu aplicación.

Esta guía cubre
APIs de sincronización / lectura de correo electrónico

Conéctate a las bandejas de entrada existentes de los usuarios. Lee, sincroniza y reacciona a los correos electrónicos en tiempo real. Autenticación vía OAuth 2.0 o IMAP. El usuario otorga acceso a su propio buzón.

Ejemplos: API de Gmail, Microsoft Graph, IMAP, Unipile
No esta guía
APIs de correo electrónico transaccional

Envía correos electrónicos salientes desde un dominio que controles. Se utiliza para recibos, notificaciones, restablecimiento de contraseñas. Sin acceso a la bandeja de entrada.

Ejemplos: SendGrid, Mailgun, Resend, Postmark
Casos prácticos

Por qué leer correos electrónicos programáticamente es importante

La capacidad de leer correos electrónicos de los usuarios a través de una API desbloquea una categoría de productos que simplemente eran imposibles solo con SMTP. Estos son los cuatro casos de uso principales que impulsan la adopción en 2026.

Sincronización de CRM y participación de ventas

Las herramientas de ventas necesitan ver cada hilo de correo electrónico entre un representante y un prospecto, automáticamente, sin iniciar sesión manualmente. Una API de correo electrónico leído extrae las conversaciones directamente de la bandeja de entrada del representante y las sincroniza con su CRM en tiempo real.

Registrar automáticamente los intercambios de correo electrónico en los registros de contactos
Extraer señales relevantes para acuerdos de los hilos de la bandeja de entrada
Detectar intención de respuesta y actualizar etapa del pipeline

Agentes de IA y Copilotos de Correo Electrónico

Los modelos de lenguaje grandes necesitan contexto. Al alimentar a tu agente de IA con un flujo en tiempo real de correos electrónicos de la bandeja de entrada, puedes crear copilotos que redacten respuestas, resuman hilos, extraigan elementos de acción y prioricen conversaciones automáticamente.

Transmitir nuevos correos electrónicos a un canal de procesamiento de LLM
Generar borradores de respuestas contextuales
Extrae tareas, fechas y compromisos de los hilos

Automatización de atención al cliente

Los equipos de soporte reciben miles de correos electrónicos al día. Una API de lectura de correos electrónicos permite que su plataforma clasifique las solicitudes entrantes, las redirija a la cola correcta y active respuestas automatizadas, todo antes de que un humano abra un ticket.

Clasificar correos de soporte por tema y urgencia
Ruta a colas de agentes basada en el contenido del correo electrónico
Dispara respuestas automáticas para patrones de solicitud comunes

Cumplimiento, Archivado y Descubrimiento electrónico

Las industrias reguladas deben retener e indexar todos los correos electrónicos. Una API de correo electrónico leído proporciona el acceso programático necesario para archivar continuamente las bandejas de entrada, marcar violaciones de políticas y producir registros de correo electrónico a pedido para revisión legal.

Archivo continuo de la bandeja de entrada para el cumplimiento de GDPR / FINRA
Detección de violaciones de políticas en buzones de empleados
Exportación de eDiscovery bajo demanda para retención legal
Análisis Profundo del Proveedor

APIs nativas para leer correos electrónicos: Gmail, Outlook e IMAP

Cada proveedor de correo electrónico importante expone su propia API de lectura con diferentes puntos de conexión, modelos de autenticación y capacidades. Así es como se ve cada uno en la práctica.

API de Gmail

OAuth 2.0

La API de Gmail es una API REST construida sobre la infraestructura de Google. Utiliza usuarios.mensajes.listar para paginar a través de un buzón y usuarios.mensajes.obtener para recuperar un mensaje completo. Admite notificaciones push a través de Google Pub/Sub, lo que permite un monitoreo en tiempo real de la bandeja de entrada sin necesidad de sondeo. Límite de tasa: 250 unidades de cuota por usuario por segundo.

gmail_leer.sh
#: Obtener los mensajes de la bandeja de entrada (API de Gmail) rizo -X OBTENER \ "https://gmail.googleapis.com/gmail/v1/users/me/messages?labelIds=INBOX&maxResults=20" \ -H "Autorización: Bearer ACCESS_TOKEN" #: Recuperar un único correo electrónico con el texto completo rizo -X OBTENER \ "https://gmail.googleapis.com/gmail/v1/users/me/messages/MESSAGE_ID?format=full" \ -H "Autorización: Bearer ACCESS_TOKEN"
Nota: Gmail devuelve los mensajes como partes MIME codificadas en base64. Debes decodificar cada parte y analizar los límites multipart tú mismo para extraer el cuerpo de texto plano, el cuerpo HTML y los archivos adjuntos.

Microsoft Graph (Outlook y Microsoft 365)

OAuth 2.0

Microsoft Graph es la API unificada para todos los servicios de Microsoft 365, incluidas las cuentas personales de Outlook, Exchange Online y los buzones de correo de Microsoft 365 para empresas. /yo/mensajes el endpoint devuelve mensajes con el cuerpo completo en una sola solicitud. La paginación utiliza $omit y $superior Parámetros de OData. Ver el completo Guía de integración de correo electrónico de Microsoft Graph para más detalles.

graph_read.sh
#: Obtener una lista de los mensajes de la bandeja de entrada (Microsoft Graph) rizo -X OBTENER \ ""https://graph.microsoft.com/v1.0/me/messages?\$top=20&\$filter=parentFolderId eq 'inbox'"' \ -H "Autorización: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" # Recuperar un único mensaje con cuerpo rizo -X OBTENER \ "https://graph.microsoft.com/v1.0/me/messages/MESSAGE_ID?\$select=subject,body,from,receivedDateTime" \ -H "Autorización: Bearer ACCESS_TOKEN"
Nota: Microsoft Graph limita a 10.000 solicitudes cada 10 minutos por aplicación y por inquilino. El contenido del cuerpo se devuelve como HTML o texto según el $seleccionar y Acepte encabezados.

IMAP

Protocolo Universal

IMAP (Protocolo de Acceso a Mensajes de Internet) es el protocolo de correo electrónico universal compatible con prácticamente todos los servidores de correo. No es una API REST, sino una conexión TCP con estado a través del puerto 993 (TLS). Se emiten comandos como TRAER, BUSCARy Ocioso en la conexión. Para una explicación más profunda, consulta nuestro Guía de integración de la API de IMAP.

imap_read.py
import imaplib, email #: Conectarse e identificarse correo = imaplib.IMAP4_SSL('imap.example.com') correo.ingresar('user@example.com', 'contraseña de aplicación') correo.elegir('BANDEJA DE ENTRADA') #: En busca de mensajes ocultos estado, ids_de_mensaje = correo.busque en(Ninguno, 'INESPERADO') para msg_id en message_ids[0].separar(): _, datos = correo.fetch(id_mensaje, '(RFC822)') msj = correo electrónico.mensaje_de_bytes(datos[0][1]) print(msg['asunto'], msg['desde'])
Nota: IMAP requiere mantener conexiones TCP de larga duración y administrar pools de conexión por usted mismo. La entrega en tiempo real utiliza el Ocioso comando, que mantiene una conexión abierta y espera notificaciones del servidor. Esto no escala fácilmente más allá de unos pocos cientos de cuentas concurrentes.
¿Y Yahoo y otros proveedores?

Yahoo Mail, ProtonMail, Zoho y otros proveedores admiten IMAP como una solución de respaldo universal, por lo que están cubiertos por el enfoque IMAP anterior. Algunos (como Yahoo) también exponen APIs propietarias limitadas, pero ninguna iguala las capacidades de la API de Gmail o Microsoft Graph. Para la mayoría de los productos multiplataforma, IMAP es la solución de respaldo universal para cualquier buzón de correo no cubierto por OAuth de Gmail u Outlook. API de correo electrónico unificada maneja esta negociación automáticamente.

Ingeniería de la Realidad

La Complejidad Oculta de Leer Correos Electrónicos a Gran Escala

Construir una integración de API para leer correos electrónicos contra un solo proveedor para una demostración lleva una tarde. Construir una que funcione de manera confiable en todos los proveedores a escala de producción es un desafío completamente diferente. Aquí está lo que realmente implica la ingeniería.

01

Flujo OAuth por Proveedor

Cada proveedor tiene su propia implementación de OAuth 2.0, requisitos de pantalla de consentimiento, ámbitos y ciclo de vida de los tokens. Admitir Gmail y Outlook significa mantener dos aplicaciones OAuth separadas, dos consolas de desarrollador, dos estrategias de renovación de tokens y dos conjuntos de requisitos de cumplimiento (Google CASA Tier 2, Microsoft Publisher Verification).

Gmail:Aplicación Google Cloud Console, Nivel CASA 2 para ámbitos sensibles, tokens de acceso de 1 hora
Outlook:Registro de aplicaciones de Azure AD, Verificación del publicador, TTL de token configurable
IMAP:Contraseñas de aplicaciones o OAuth (Gmail IMAP utiliza el mismo flujo de Google OAuth)
02

Diferencias de paginación

Cada proveedor pagina de forma diferente. Gmail usa tokens de página opacos. Microsoft Graph usa OData. $omit y próximo enlace cursores. IMAP usa rangos de UID numéricos. Implementar una abstracción de paginación coherente en los tres requiere un código adaptador no trivial.

Gmail:pageToken cursor, máximo 500 resultados por página
GráficoURL de @odata.nextLink, parámetros $top/$skip
IMAP:UID FETCH rangos, CONDSTORE para sincronización incremental
03

Análisis MIME

Los correos electrónicos llegan como documentos MIME sin procesar con límites multipart anidados, codificación base64 o quoted-printable, múltiples conjuntos de caracteres y archivos adjuntos en línea. Gmail devuelve partes codificadas en base64url. IMAP devuelve RFC 822 sin procesar. Ninguno le ofrece un cuerpo de texto plano limpio sin analizar todo el árbol MIME.

RiesgoLos caracteres internacionales, los emoji y el texto RTL introducen casos extremos de codificación que corrompen el contenido del cuerpo.
Adjuntos:Debe recorrer el árbol MIME para encontrar las partes adjuntas de Content-Disposition.
04

Límites de Tasa y Retroceso

Gmail aplica 250 unidades de cuota por usuario por segundo (listar cuesta 5 unidades, obtener 5 unidades). Microsoft Graph limita a 10.000 solicitudes cada 10 minutos por aplicación por inquilino. Ambos devuelven errores 429 que requieren retroceso exponencial con jitter. Con 1.000 cuentas vinculadas, la gestión de límites de tasa se convierte en un problema de ingeniería completo.

Gmail:250 unidades de cuota/seg/usuario. Límite diario: 1000 millones de unidades
Gráfico10.000 solicitudes / 10 min / aplicación / inquilino. Encabezado Retry-After
IMAP:Específico del proveedor, típicamente 10-20 conexiones concurrentes por cuenta
05

En tiempo real: Webhooks vs. Sondeo vs. IDLE

Recibir notificaciones cuando llega un nuevo correo electrónico requiere mecanismos completamente diferentes por proveedor. Gmail utiliza suscripciones de notificación push de Google Pub/Sub que deben renovarse cada 7 días. Microsoft Graph utiliza suscripciones de notificación de cambios con una vida útil máxima de 4.230 minutos. IMAP utiliza el comando IDLE, que mantiene abierta una conexión TCP persistente por cuenta.

Gmail:Pub/Sub push, caducidad de 7 días, requiere ciclo de renovación
Gráficosuscripción de cambio de notificaciones, expiración máxima de ~3 días
IMAP:Comando IDLE, 1 conexión TCP persistente por cuenta
06

Inconsistencias en el hilo entre proveedores

Gmail agrupa los mensajes en hilos de forma nativa. Microsoft Graph tiene un campo conversationId pero los hilos se comportan de manera diferente a Gmail. IMAP no tiene subprocesamiento nativo; reconstruyes hilos emparejando manualmente las cabeceras References e In-Reply-To. La construcción de una vista de hilo unificada entre proveedores requiere una lógica de normalización significativa.

Gmail:threadId nativo, messages.list?labelIds=INBOX devuelve grupos de hilos
GráficoconversationId, pero no equivalente a los hilos de Gmail
IMAP:Debe analizar las cabeceras Message-ID / References manualmente
Arquitectura

Lea la arquitectura de la API de correo electrónico: 3 enfoques comparados

No existe una arquitectura "correcta" única para leer correos electrónicos. El enfoque adecuado depende de cuántos proveedores necesites admitir, tu capacidad de ingeniería y tus requisitos de escala. Aquí tienes una comparación honesta.

Acercamiento Pros Pons Cuándo usar
APIs de proveedor directo
Gmail API, Microsoft Graph		 Nivel gratuito, acceso a todas las funciones, sin latencia intermedia Configuración de OAuth por proveedor, análisis MIME, gestión de límites de tasa separados, sin normalización entre proveedores Solo proveedor
IMAP autohospedado
imaplib, node-imap		 Protocolo universal, funciona con cualquier buzón, no requiere aplicación OAuth Conexiones TCP con estado, sin notificaciones push (polling o IDLE), gestión de pool de conexiones, lento a escala Legado / solo local
API unificada de lectura de correo electrónico
Unipile		 Un endpoint para todos los proveedores, respuesta JSON normalizada, OAuth gestionado, webhooks unificados, lógica de reintentos incorporada Costo adicional de llamada a la API por cuenta vinculada, dependencia externa Productos multi-proveedor
APIs de proveedor directo
Gmail API, Microsoft Graph
Pros Nivel gratuito, acceso a todas las funciones, sin latencia intermedia
Pons Configuración de OAuth por proveedor, análisis MIME, gestión de límites de tasa separados, sin normalización entre proveedores
Cuándo usar Solo proveedor
IMAP autohospedado
imaplib, node-imap
Pros Protocolo universal, funciona con cualquier buzón, no requiere aplicación OAuth
Pons Conexiones TCP con estado, sin notificaciones push (polling o IDLE), gestión de pool de conexiones, lento a escala
Cuándo usar Legado / solo local
API unificada de lectura de correo electrónico
Unipile
Pros Un endpoint para todos los proveedores, respuesta JSON normalizada, OAuth gestionado, webhooks unificados, lógica de reintentos incorporada
Pons Costo adicional de llamada a la API por cuenta vinculada, dependencia externa
Cuándo usar Productos multi-proveedor
El mejor para un solo proveedor
API de Proveedor Directo

Si todos los usuarios de tu producto usan Gmail, intégrate directamente contra la API de Gmail. Obtendrás paridad total de funciones, sin costo adicional y acceso a funciones específicas de Gmail como etiquetas, hilos y notificaciones push de Pub/Sub.

Lo mejor para sistemas heredados
IMAP autohospedado

Servidores de correo locales, implementaciones empresariales de Exchange sin acceso a la API de Graph o cualquier escenario donde OAuth no esté disponible. Utilice IMAP como recurso de contingencia, no como estrategia principal para nuevos productos.

Lo mejor para productos SaaS
API Unificada para Leer Correos Electrónicos

Cuando tus usuarios tienen buzones de Gmail, Outlook y IMAP y necesitas una API de lectura de correos electrónicos coherente en todos ellos, una capa unificada como Unipile elimina por completo el problema de la integración con múltiples proveedores.

Configuración en 5 minutos

Leer correos electrónicos con la API Unificada de Lectura de Correos Electrónicos de Unipile

Unipile abstrae la API de Gmail, Microsoft Graph e IMAP a través de una única API de lectura de correos electrónicos. Un flujo de OAuth, un endpoint, un formato JSON normalizado: independientemente del proveedor en el que resida el buzón de tu usuario. Así es como puedes leer tu primer buzón en menos de 5 minutos.

1
Autenticar a un usuario con el enlace de autenticación alojado

Genera una URL de autenticación alojada desde tu panel de control de Unipile. Envía este enlace a tu usuario. Él completará el flujo de consentimiento OAuth para su proveedor (credenciales de Gmail, Outlook o IMAP) en la página alojada de Unipile. Sin configuración de aplicación OAuth, sin configuración de URI de redirección de tu parte. Ver guía de API de correo electrónico unificada para el flujo de autenticación completo.

auth_link.sh
# Genera un enlace de autenticación alojado para tu usuario rizo -X Publicación \ "https://api3.unipile.com:PUERTO/api/v1/hosted/accounts/link" \ -H "X-API-KEY: TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{"type":"EMAIL","name":"user@example.com","success_redirect_url":"https://yourapp.com/connected"}' Respuesta #: { "url": "https://auth.unipile.com/..." } # Envía esta URL a tu usuario; él completará el proceso de OAuth en su proveedor
2
Listar correos de la bandeja de entrada - GET /api/v1/emails

Una vez que el usuario haya vinculado su cuenta, llame al endpoint de correos electrónicos con su account_id. La respuesta es idéntica independientemente de si el buzón subyacente es Gmail, Outlook o IMAP.

list_emails.sh
#: Lista de correos electrónicos de la bandeja de entrada (funciona con Gmail, Outlook e IMAP) rizo -X OBTENER \ "https://api3.unipile.com:PUERTO/api/v1/emails?account_id=ID_CUENTA&limit=50" \ -H "X-API-KEY: TU_API_KEY" # Filtrar por carpeta rizo "...?account_id=ACCOUNT_ID&folder=INBOX&limit=50" -H "X-API-KEY: TU_API_KEY" #: Filtrar solo los mensajes no leídos rizo "...?account_id=ACCOUNT_ID&unread=true" -H "X-API-KEY: TU_API_KEY"
200 OK - JSON normalizado, misma forma para todos los proveedores
3
Obtener un único correo electrónico con cuerpo y archivos adjuntos

Recupera un correo electrónico completo por ID. Unipile devuelve un objeto decodificado y normalizado con el cuerpo en texto plano, el cuerpo HTML y metadatos de archivos adjuntos, sin necesidad de análisis MIME de tu parte.

get_email.sh
#: Recuperar un único correo electrónico con el texto completo y los archivos adjuntos rizo -X OBTENER \ "https://api3.unipile.com:PUERTO/api/v1/emails/ID_DEL_CORREO" \ -H "X-API-KEY: TU_API_KEY" Campos de respuesta # (siempre normalizados): # { "id", "asunto", "fecha", "remitente", "destinatarios", # "body", "body_plain", "attachments": [{ "id", "filename", "size" }] }
4
Recibir nuevos correos electrónicos en tiempo real mediante webhooks

Registra un punto de enlace de webhook en tu panel de Unipile. Unipile abstrae las notificaciones de cambio de Gmail Pub/Sub, Microsoft Graph e IMAP IDLE en una sola email.recibido evento. Sin renovación de suscripción, sin grupo de conexiones inactivo que administrar.

webhook_handler.js
// Unipile llama a tu endpoint cuando llega un nuevo correo electrónico // Mismo evento para usuarios de Gmail, Outlook e IMAP aplicación.Correo electrónico:('/webhooks/email', (req, res) => { const { evento, id_cuenta, id_correo_electronico } = req.body; si (evento === 'email.recibido') { // Obtener los detalles completos del correo electrónico procesarNuevoCorreoElectrónico(id_cuenta, id_correo_electronico); } res.estadoEnviado(200); });
Un evento de webhook reemplaza las suscripciones de Gmail Pub/Sub + Graph + IMAP IDLE
¿Quieres la referencia de integración completa?

La Guía Completa de la API de Correo Electrónico cubre la autenticación, todos los puntos de acceso, paginación, descargas de adjuntos, seguridad y cumplimiento en detalle.

Leer la Guía de la API de correo electrónico
Ejemplos de código

Lectura de Correos Electrónicos: Ejemplos de Código por Lenguaje

Fragmentos listos para producción para leer correos electrónicos con la API unificada de lectura de correos electrónicos de Unipile. Todos los ejemplos leen desde cuentas de Gmail, Outlook y IMAP con el mismo código.

Node.js / TypeScript
Python
Ir
readEmails.ts
import fetch from 'node-fetch'; const BASE = 'https://api3.unipile.com:PUERTO/api/v1'; const CLAVE_API = process.env.UNIPILE_API_KEY!; interfaz Correo electrónico { id: cadena; tema: cadena; fecha: cadena; de_asistente: { nombre_visible: cadena; identificador: cadena }; body: cadena; cuerpo_texto cadena; adjuntos: { id: cadena; nombre del archivo: cadena; tamaño: número }[]; } // Listar correos electrónicos de la bandeja de entrada - funciona para Gmail, Outlook e IMAP async function listEmails(idCuenta: cadena, límite = 50) { const res = await fetch( `${BASE}/emails?account_id=${accountId}&limit;=${limit}&folder;=INBOX`, { encabezados: { 'X-API-KEY': CLAVE_API } } ); const datos = await res.json(); return datos.elementos como Correo electrónico[]; } // Recuperar un solo correo electrónico con el cuerpo completo + archivos adjuntos async function obtenerCorreoElectronico(emailId: cadena) { const res = await fetch(`${BASE}/emails/${emailId}`, { encabezados: { 'X-API-KEY': CLAVE_API } } ); return await res.json() como Correo electrónico; } // Uso const correos electrónicos = await listEmails('acc_01abc...'); correos electrónicos.para cada uno(e => console.log(e.asunto, e.de_asistente.identificador));
Guía completa de la API de correo electrónico para JavaScript
leer_correos.py
import os import solicita BASE = "https://api3.unipile.com:PORT/api/v1" ENCABEZADOS = {"Clave API X"os.environ["UNIPILE_API_KEY"]} def listar_correos(account_id: str, limite: int = 50) -> lista: "Listar correos electrónicos de la bandeja de entrada - funciona para Gmail, Outlook e IMAP." respuesta = solicitudes.consiga( f"{BASE}/correos", headers=cabeceras, params={ "account_id": id_cuenta, "límite"límite, "carpeta": "Bandeja de entrada", }, ) resp.lanzar_para_estado() return resp.json()["artículos"] def obtener_correo(email_id: str) -> dict: """Recuperar un solo correo electrónico con cuerpo y archivos adjuntos.""" respuesta = solicitudes.consiga(f"{BASE}/correos/{email_id}", headers=HEADERS) resp.lanzar_para_estado() return resp.json() # Uso correos electrónicos = listar_correos("acc_01abc...") para email en correos electrónicos print(correo electrónico"Asunto", correo electrónico["asistente_remitente"]["identificador"]) #: Recuperar el texto completo del primer correo electrónico completo = obtener_correocorreos[0]["id"]) print(completo"body_plain"])
Guía completa de la API de correo electrónico para Python
read_emails.go
paquete principal import ( "codificación/json" "fmt" "net/http" "os" ) tipo Correo electrónico struct { ID cadena `json:"id"` Asunto cadena `json:"asunto"` CuerpoPlano cadena `json:"cuerpo_plano"` } tipo RespuestaLista struct { Artículos []Correo electrónico `json:"items"` } función listEmails(accountID cadena) ([]Correo electrónico, error) { url := "https://api3.unipile.com:PORT/api/v1/emails?account_id=" + ID de cuenta req, _ := http.NuevaSolicitud("CONSEGUIR", dirección web, nulo) req.Header.Establecer("Clave API X", os.Getenv("UNIPILE_API_KEY")) resp, err := http.DefaultClient.Visite(solicitud) si err != nulo { return nulo, error } aplazar resp.Cuerpo.Cerrar() variable resultado RespuestaLista json.Decodificador(resp.Cuerpo).Decodificar(&resultado) return result.Items, nulo } función principal() { correos electrónicos, _ := listEmails("acc_01abc...") para _, e := rango correos electrónicos { formato.Imprimir(e.Asunto) } }
En tiempo real

Lectura de correo electrónico en tiempo real: Webhooks vs. Sondeo

Saber cuándo llega un nuevo correo electrónico es tan importante como poder leerlo. Hay tres mecanismos disponibles, cada uno con características operativas muy diferentes a escala.

Evitar a escala

Sondeo

Tu aplicación llama al punto final de lista de correos electrónicos mediante un temporizador (cada 30 s, cada 5 minutos). Fácil de implementar pero consume cuota, introduce latencia y no escala más allá de un puñado de cuentas.

Simple - sin configuración del lado del servidor
Facturar la cuota de la API proporcionalmente a las cuentas x frecuencia
Encuesta de 5 minutos = retraso de notificación de 5 minutos
No escala más allá de ~100 cuentas activas
Específico del proveedor

Webhooks del Proveedor Nativo

Las notificaciones push de Gmail Pub/Sub y Microsoft Graph envían eventos a tu servidor inmediatamente. Rápido y eficiente en cuota, pero cada uno requiere configuración separada, lógica de renovación separada y esquemas de eventos diferentes.

Entrega casi instantánea (segundos)
Eficiente en cuota - solo se activa en correos electrónicos nuevos
Gmail: La suscripción de Pub/Sub expira cada 7 días
Gráfico: suscripción máx ~3 días, debe renovarse
IMAP IDLE: 1 conexión TCP por cuenta
Recomendado

Unipile Unificados Webhooks

Unipile abstrae todos los mecanismos de push de los proveedores detrás de un único email.recibido event. Un extremo recibe notificaciones para cuentas de Gmail, Outlook e IMAP por igual, con la renovación automática de suscripciones manejada internamente.

Una URL de webhook para todos los proveedores
Renovación automática de Pub/Sub y gráfico
IMAP IDLE gestionado internamente por cuenta
Carga útil normalizada - mismos campos cada vez
Cómo Unipile abstrae la entrega de correo electrónico en tiempo real

Bajo el capó, Unipile gestiona suscripciones de Pub/Sub de Gmail, suscripciones de notificaciones de cambios de Microsoft Graph y conexiones IMAP IDLE, por cuenta vinculada, renovadas automáticamente. Su aplicación registra una URL de webhook y recibe un evento normalizado independientemente del proveedor subyacente.

Gmail Pub/Sub
+
Suscripciones de gráficos
+
IMAP IDLE
->
evento.email.recibido
Seguridad y conformidad

Seguridad y Cumplimiento al Leer Correos Electrónicos de Usuarios

Acceder a los correos electrónicos de los usuarios conlleva importantes responsabilidades de seguridad y legales. Aquí están las cuatro áreas que debe abordar antes de lanzar una integración de API de lectura de correos electrónicos a producción.

Minimización de Alcance de OAuth

Siempre solicite el alcance mínimo de OAuth requerido. Para leer correos electrónicos, use ámbitos de solo lectura - nunca solicites permisos de envío o redacción si tu aplicación solo necesita acceso a la bandeja de entrada. El alcance de solo lectura de Gmail es gmail.lectura. El equivalente de Microsoft Graph es Mail.Read. Solicitar ámbitos amplios activa procesos de revisión más estrictos de Google y Microsoft y reduce la confianza del usuario en la pantalla de consentimiento.

Mejores prácticas de almacenamiento de tokens

Los tokens de acceso y los tokens de actualización de OAuth son credenciales. Almacénelos cifrado en reposo Utilizando AES-256 o equivalente, nunca en texto plano en su base de datos. Rote las claves de cifrado según un programa. Nunca registre tokens en los registros de la aplicación. Implemente la revocación de tokens cuando un usuario desconecte su cuenta: llame al punto final de revocación del proveedor, no elimine simplemente el registro de la base de datos.

RGPD y Residencia de Datos

Los cuerpos de correo electrónico a menudo contienen datos personales cubiertos por el RGPD. Debe documentar en su política de privacidad exactamente qué datos de correo electrónico recopila, conserva, procesa y durante cuánto tiempo. Implemente un flujo de eliminación de datos que elimine el contenido del correo electrónico cuando un usuario solicite el borrado. Si almacena contenido de correo electrónico en su propia infraestructura, considere los requisitos de residencia de datos para los clientes de la UE.

Verificación de Google CASA y Microsoft Publisher

Aplicaciones que solicitan ámbitos de Gmail confidenciales (incluidos gmail.lecturadebe completar el Google CASA Nivel 2 evaluación de seguridad antes de recibir permiso para superar el límite de prueba de 100 usuarios. Microsoft requiere la Verificación del editor para las aplicaciones que solicitan ciertas ámbitos de Graph. Ambos procesos llevan semanas; planifique en consecuencia antes de su fecha de lanzamiento. Al utilizar Unipile, heredará estas certificaciones de la capa de plataforma.

Certificaciones de cumplimiento de Unipile

Unipile maneja la certificación de Gmail CASA Nivel 2, la Verificación de Microsoft Publisher, la auditoría SOC 2 Tipo II y los acuerdos de procesamiento de datos GDPR a nivel de plataforma. Los productos construidos sobre Unipile heredan estas certificaciones en lugar de completarlas de forma independiente.

SOC 2 Tipo II
Google CASA Nivel 2
Conformidad con el GDPR
Ámbitos de solo lectura de OAuth 2.0
Precios

Leer precios de API de correo electrónico: niveles gratuitos y modelos de costos

Los niveles gratuitos para las API de proveedores nativos son generosos a bajo escala, pero los costos ocultos aparecen cuando necesitas dar soporte a múltiples proveedores, administrar la actualización de tokens a gran escala o alcanzar los límites de frecuencia. Aquí tienes un desglose honesto.

Proveedor Nivel gratuito Modelo de costos Límite de tasa Costos ocultos
API de Gmail Gratis con cuotas Unidades de cuota por solicitud. Sin facturación por cuenta 250 unidades/segundo/usuario, 1 mil millones de unidades/día Revisión de CASA Nivel 2, análisis MIME, lógica de renovación de Pub/Sub
Microsoft Graph Gratis con limitación Incluido con el inquilino de Microsoft 365. Sin tarifa por llamada 10.000 req/10 min/app/inquilino Proceso de Verificación del Editor, renovación de suscripción, aplicaciones OAuth por inquilino
IMAP (autoalojado) Protocolo libre Sin costo de API. Costo de infraestructura para pools de conexión Específico del proveedor, ~10-20 conexiones/cuenta Infraestructura de servidores, gestión de conexiones inactivas, sin soporte push
Unipile 7 días de prueba gratuita Por cuenta vinculada por mes. Ver Nivel gratuito de API de correo electrónico Gestionado internamente, lógica de reintento incorporada Costo de llamada a la API por cuenta, compensado por la eliminación de ingeniería de OAuth/MIME
API de Gmail
Gratis con cuotas
Modelo de costos Unidades de cuota por solicitud. Sin facturación por cuenta
Límite de tasa 250 unidades/segundo/usuario, 1 mil millones de unidades/día
Costos ocultos Revisión de CASA Nivel 2, análisis MIME, lógica de renovación de Pub/Sub
Microsoft Graph
Gratis con limitación
Modelo de costos Incluido con el inquilino de Microsoft 365. Sin tarifa por llamada
Límite de tasa 10.000 req/10 min/app/inquilino
Costos ocultos Proceso de Verificación del Editor, renovación de suscripción, aplicaciones OAuth por inquilino
IMAP (autoalojado)
Protocolo libre
Modelo de costos Sin costo de API. Costo de infraestructura para pools de conexión
Límite de tasa Específico del proveedor, ~10-20 conexiones/cuenta
Costos ocultos Infraestructura de servidores, gestión de conexiones inactivas, sin soporte push
Unipile
7 días de prueba gratuita
Modelo de costos Por cuenta vinculada por mes. Ver Nivel gratuito de API de correo electrónico
Límite de tasa Gestionado internamente, lógica de reintento incorporada
Costos ocultos Costo de llamada a la API por cuenta, compensado por la eliminación de ingeniería de OAuth/MIME

¿Empezando con una API de correo electrónico de lectura gratuita? La API de Gmail y Microsoft Graph ofrecen acceso gratuito dentro de los límites de cuota. Unipile ofrece una prueba gratuita de 7 días sin necesidad de tarjeta de crédito, cubriendo cuentas vinculadas de Gmail, Outlook e IMAP.

Empezar prueba gratis
Errores comunes

Errores comunes al crear una integración de correo electrónico de lectura

Estos son los errores que causan consistentemente incidentes de producción en los equipos que implementan su primera integración de API de lectura de correo electrónico. Apréndelos antes de que te ocurran.

01
Agotamiento de cuotas en Gmail a escala

Las 250 unidades de cuota por segundo por usuario de Gmail suenan generosas hasta que se tienen 500 cuentas y se necesita hacer una sincronización inicial de la bandeja de entrada. Listar 500 mensajes cuesta 2500 unidades; recuperar cada mensaje completo cuesta otras 2500. Las sincronizaciones iniciales de buzones de correo grandes pueden agotar las cuotas diarias en cuestión de horas.

Corregir: Implementa un retroceso exponencial en respuestas 429, prioriza mensajes recientes para la sincronización inicial y utiliza solicitudes por lotes donde estén disponibles para reducir la sobrecarga por llamada.
02
Fallos silenciosos de actualización de tokens

Los tokens de actualización de OAuth caducan silenciosamente. Google los revoca después de 6 meses de inactividad, después de un cambio de contraseña o cuando un usuario revoca el acceso desde la configuración de su Cuenta de Google. Si la lógica de actualización de su token no detecta un error 401 y no lo muestra al usuario, su aplicación simplemente dejará de leer correos electrónicos sin ningún error visible.

Corregir: Trata las respuestas 401 como eventos de desconexión de cuenta. Notifica al usuario y solicita la reautenticación. Almacena un última_sincronización_en marca de tiempo y alerta cuando excede su intervalo de sincronización esperado.
03
Correos electrónicos faltantes debido a filtros de carpetas incorrectos

Las etiquetas de Gmail y las carpetas de IMAP no son conceptos equivalentes. El sistema de Gmail CONTENEDOR La etiqueta no incluye los mensajes que se han archivado (eliminados de la bandeja de entrada, pero no borrados). La carpeta de la bandeja de entrada de Microsoft Graph excluye la bandeja de entrada destacada frente a otras divisiones de paneles, a menos que se consulten ambas. Los equipos suelen descubrir que les faltan entre 20 y 40% de mensajes debido a suposiciones erróneas sobre las carpetas.

Corregir: Prueba tus consultas de carpetas con cuentas reales, incluidos mensajes archivados, filtrados y categorizados. Para una sincronización completa, considera consultar TODOS mensajes (no solo la BANDEJA DE ENTRADA) y filtrado por fecha de tu lado.
04
Errores de codificación en correos electrónicos internacionales

Los cuerpos de los correos electrónicos llegan en una amplia gama de codificaciones de caracteres: UTF-8, ISO-8859-1, Windows-1252, Shift-JIS. Gmail devuelve partes codificadas en base64url. IMAP devuelve partes codificadas en quoted-printable. Decodificar una codificación como otra produce texto en el cuerpo corrupto que es invisible en tu entorno de prueba local (que probablemente solo envía correos electrónicos ASCII).

Corregir: Siempre decodifique las partes MIME según su Content-Transfer-Encoding y volver a codificar a UTF-8. Pruebe específicamente con contenido de correo electrónico con mucho japonés, árabe y emojis.
05
Inconsistencias en los hilos entre proveedores

Crear una vista de hilos unificada entre cuentas de Gmail, Outlook y IMAP requiere normalizar tres modelos de hilos completamente diferentes. Gmail tiene identificadores de hilo nativos. Outlook tiene identificadores de conversación que se comportan de manera diferente. IMAP no tiene ningún hilo nativo; reconstruyes los hilos a partir de ID-Mensaje, Referenciasy En respuesta a encabezados, que no siempre están presentes o son correctos.

Corregir: Una API unificada para leer correos electrónicos como Unipile normaliza el encadenamiento en un modelo coherente a través de todos los proveedores, eliminando la necesidad de implementar lógica de reconstrucción de hilos específica del proveedor.
PREGUNTAS FRECUENTES

Leer API de correo electrónico - Preguntas frecuentes

Las preguntas más comunes de los desarrolladores que crean su primera integración de API de lectura de correo electrónico.

01
¿Qué es una API para leer correos electrónicos?
A leer correo electrónico API es una interfaz HTTP que permite que tu aplicación se autentique contra el buzón de correo existente de un usuario (a través de credenciales OAuth 2.0 o IMAP) y recupere mensajes de correo electrónico programáticamente. Es distinta de las API de correo transaccional como SendGrid o Mailgun, que envían correo saliente desde un dominio que controlas. Las API de lectura de correo operan en la cuenta de Gmail, Outlook o IMAP del propio usuario. Ver la Comparación completa de proveedores de API de correo electrónico para tener contexto del ecosistema más amplio.
02
¿Puedo leer el correo electrónico de alguien con una API?
Solo puedes leer correos electrónicos de cuentas cuyo propietario del buzón haya otorgado explícitamente acceso a tu aplicación a través del consentimiento de OAuth 2.0. El usuario debe autorizar tu aplicación en la pantalla de consentimiento de Google o Microsoft. No puedes acceder a los correos electrónicos sin el consentimiento del propietario de la cuenta; intentar hacerlo viola los términos de servicio del proveedor y la ley aplicable en la mayoría de las jurisdicciones.
03
¿Cómo leo correos electrónicos usando la API de Gmail?
Para leer correos electrónicos con la API de Gmail: crea un proyecto de Google Cloud, habilita la API de Gmail, configura un cliente OAuth 2.0, solicita los gmail.lectura ámbito, obtener un token de acceso a través del consentimiento de OAuth, luego llamar Obtener /gmail/v1/usuarios/yo/mensajes listar mensajes y GET /usuarios/yo/mensajes/{id}?formato=completo para recuperar correos electrónicos individuales. Los mensajes se devuelven como partes MIME codificadas en base64url que debes decodificar.
04
¿Cuál es la diferencia entre IMAP y la API de Gmail?
La API de Gmail es una API REST moderna con OAuth 2.0, notificaciones push a través de Google Pub/Sub y respuestas JSON. IMAP es un protocolo TCP universal compatible con todos los proveedores de correo electrónico, utiliza conexiones con estado y comandos de texto. La API de Gmail es más capaz para casos de uso exclusivos de Gmail (push en tiempo real, acceso a hilos, gestión de etiquetas). IMAP proporciona una cobertura universal en todos los proveedores, pero requiere sondeos o conexiones IDLE y no tiene una interfaz REST nativa. Lee nuestra Guía de integración de la API de IMAP para una comparación más profunda.
05
¿Hay una API gratuita para leer correos electrónicos?
Sí. La API de Gmail es gratuita dentro de los límites de cuota de Google (250 unidades/segundo/usuario, 1000 millones de unidades/día). Microsoft Graph para Outlook es gratuito con límites de limitación. IMAP es un protocolo abierto y gratuito. Para soporte multi-proveedor, Unipile ofrece una prueba gratuita de 7 días que cubre cuentas vinculadas de Gmail, Outlook e IMAP. Ver nuestro guía de API de correo electrónico gratuita para una comparación completa de los niveles gratuitos y sus límites en el mundo real.
06
¿Cómo puedo leer correos electrónicos de múltiples proveedores con una sola API?
Utilice una API unificada de lectura de correo electrónico como Unipile. Unipile expone un único endpoint.GET /api/v1/emailsque devuelve JSON normalizado para cuentas de Gmail, Outlook e IMAP. Autenticas a los usuarios una vez a través de un enlace OAuth alojado, y Unipile se encarga de los flujos OAuth específicos del proveedor, el análisis MIME y la abstracción de webhooks en tiempo real detrás de una única interfaz coherente. Ver nuestro Guía de la API de correo electrónico para la referencia completa.
07
¿Puedo leer los archivos adjuntos de correo electrónico a través de la API?
Sí. La API de Gmail devuelve metadatos de archivos adjuntos en la carga útil del mensaje y proporciona un punto final separado para descargar datos de archivos adjuntos por ID. Microsoft Graph devuelve archivos adjuntos a través de /mensajes/{id}/adjuntos. IMAP requiere analizar el árbol MIME para identificar partes de archivos adjuntos. Con Unipile, los metadatos de los archivos adjuntos (nombre del archivo, tamaño, tipo MIME) se incluyen en la respuesta del correo electrónico y el contenido del archivo adjunto está disponible a través de un punto final dedicado, sin necesidad de analizar MIME.
08
¿Cómo me notifico cuando llega un nuevo correo electrónico?
Cada proveedor tiene un mecanismo diferente: Gmail utiliza suscripciones push de Google Pub/Sub (expiran cada 7 días, requieren renovación). Microsoft Graph utiliza suscripciones de notificación de cambios (expiran después de ~3 días). IMAP utiliza el comando IDLE a través de una conexión TCP persistente. Alternativamente, Unipile abstrae los tres en una sola email.recibido evento de webhook que se activa para cuentas de Gmail, Outlook e IMAP con gestión automática de suscripciones manejada internamente.
09
Los límites de frecuencia para leer correos electrónicos en Gmail y Outlook varían según la aplicación y el método que utilices para acceder a tus correos. En general, estos límites están diseñados para evitar el abuso, el spam y para garantizar la estabilidad del servicio. Aquí te presento una descripción general de los límites para los métodos más comunes: **Gmail:** * **API de Gmail (Método recomendado para aplicaciones):** * **Límites por usuario:** Por defecto, la API de Gmail tiene un límite de 1000 millones de unidades por día y 100 unidades por segundo por proyecto. Sin embargo, lo más relevante para la lectura de correos es el límite de **1000 millones de unidades por día por usuario** y **100 unidades por segundo por usuario**. * **Unidades de cuota:** Las operaciones más comunes (como "Listar mensajes" o "Obtener un mensaje") consumen unidades de cuota. Leer la lista de mensajes en una bandeja de entrada puede consumir más unidades que leer un solo mensaje específico. * **Solicitudes para aumentar límites:** Si necesitas un mayor volumen de solicitudes, puedes solicitar un aumento de cuota a Google Cloud. * **IMAP/POP3 (Protocolos de acceso a correos):** * Google no publica límites de frecuencia exactos para las conexiones IMAP/POP3 que sean comparables a los de la API. Sin embargo, si accedes a tu cuenta de Gmail a través de un cliente de correo (Outlook Desktop, Thunderbird, etc.) mediante IMAP o POP3, los accesos masivos y frecuentes pueden ser marcados como actividad sospechosa. * Si hay demasiadas solicitudes en un corto período, es posible que temporalmente se te bloquee el acceso o se te pida que verifiques tu identidad para confirmar que no eres un bot. **Outlook (Microsoft 365 y Exchange Online):** * **Microsoft Graph API:** * **Límites de solicitudes por usuario:** Microsoft Graph tiene una estructura de límites más detallada. Para la mayoría de las operaciones relacionadas con correos electrónicos (`/me/messages` o `/users/{id}/messages`), el límite general es de **10,000 solicitudes por 10 minutos por usuario**. * **Límites de solicitudes por inquilino:** También hay límites a nivel de inquilino (para toda tu organización), que suelen ser mucho mayores, pero el límite por usuario es el que más probablemente afectará a la lectura de correos de una cuenta específica. * **Throttling (Estrangulamiento):** Si excedes estos límites, recibirás una respuesta `429 Too Many Requests` con un encabezado `Retry-After` que indica cuánto tiempo debes esperar antes de reintentar. * **IMAP/POP3/SMTP:** * Similar a Gmail, los límites para el acceso a través de protocolos POP, IMAP y SMTP no se publican explícitamente con el mismo nivel de detalle que las APIs. * Sin embargo, Microsoft también implementa mecanismos para detectar y prevenir el abuso. Los clientes de correo que realicen un número excesivo de conexiones o solicitudes de forma muy rápida pueden experimentar retrasos o bloqueos temporales. El objetivo es proteger las cuentas contra accesos no autorizados o envíos masivos de spam. **Consideraciones Generales:** 1. **Cliente de correo vs. API:** Las APIs (Gmail API, Microsoft Graph) suelen tener límites más definidos y son la opción recomendada para construir aplicaciones que interactúan con correos. Los clientes de correo (Outlook Desktop, aplicaciones móviles, etc.) que usan IMAP/POP3/SMTP se benefician de las optimizaciones internas del cliente y del servicio, pero también están sujetos a limitaciones. 2. **Operaciones específicas:** No es solo "leer un correo". Listar correos en una bandeja, obtener los detalles de un correo, descargar contenido adjunto, etc., consumen diferentes "unidades" o cuentan como solicitudes distintas. 3. **Buenas prácticas:** Independientemente del servicio, es crucial implementar lógica de reintentos con retroceso exponencial (exponential backoff) en tus aplicaciones para manejar las respuestas de estrangulamiento y evitar saturar los servidores. 4. **Documentación oficial:** Para obtener los detalles más precisos, siempre es mejor consultar la documentación oficial de los límites de cuota y estrangulamiento de Google Cloud (para Gmail) y de Microsoft Graph (para Outlook/Exchange Online). En resumen, si estás desarrollando una aplicación, usa las APIs y respeta sus límites. Si usas un cliente de correo común, no deberías encontrar problemas a menos que estés realizando operaciones masivas o inusualmente frecuentes, lo que podría activarse como una medida de seguridad.
API de Gmail: 250 unidades de cuota por usuario por segundo. Listar mensajes cuesta 5 unidades, obtener un mensaje completo cuesta 5 unidades. El límite diario es de mil millones de unidades de cuota. Microsoft Graph: 10.000 solicitudes por cada 10 minutos por aplicación por tenant. Ambos devuelven HTTP 429 cuando se limita, con un Reintentar después Encabezado. Implementar retroceso exponencial con fluctuación para la confiabilidad en producción. Los límites de IMAP son específicos del proveedor, típicamente de 10 a 20 conexiones simultáneas por cuenta.
10
¿Leer correos electrónicos de usuarios a través de API cumple con el RGPD?
Leer correos electrónicos de usuarios a través de la API puede cumplir con el GDPR si se implementa correctamente. Los requisitos incluyen: consentimiento explícito del usuario a través de OAuth (la pantalla de consentimiento cumple el requisito de base legal), una política de privacidad que documente qué datos de correo electrónico recopila y retiene, un mecanismo de eliminación de datos para las solicitudes de borrado y un acuerdo de procesamiento de datos con cualquier capa de API de terceros que utilice. Unipile cuenta con certificación SOC 2 Tipo II y cumple con el RGPD., simplificando la documentación de cumplimiento para los productos creados en la plataforma.

¿Aún tiene preguntas? Habla con un desarrollador que haya implementado integraciones de API de lectura de correos electrónicos a escala, tanto en Gmail, Outlook como en IMAP.

Hable con un experto
es_ESES
en_USEN fr_FRFR de_DEDE it_ITIT pt_BRBR nl_NLNL pl_PLPL tr_TRTR es_ESES