LinkedIn
Instagram
WhatsApp
Telegrama
Calendario de Google
Únase a la comunidad SlackMicrosoft Graph API Correo electrónico: Guía Completa de Integración para Desarrolladores (2026)
La API de Microsoft Graph es el punto final REST unificado para acceder a los datos de correo electrónico de Outlook y Exchange: leer, enviar, buscar y recibir webhooks para cada evento del buzón. Esta guía le guía a través de la configuración de OAuth 2.0, ejemplos de código en vivo, límites de frecuencia y cómo unificar Microsoft Graph con Gmail e IMAP bajo un único SDK.
import solicita
# API Unificada de Correo Electrónico de Unipile
# Lee correos electrónicos de Outlook a través de Microsoft Graph
BASE = "https://api.unipile.com:13465/api/v1"
ENCABEZADOS = {
"Clave API X": "TU_TOKEN_DE_ACCESO",
"Aceptar": "application/json"
}
def obtener_correos_de_outlook(id_cuenta, límite=20):
r = solicitudes.consiga(
f"{BASE}/correos",
headers=cabeceras,
params={
"account_id": id_cuenta,
"límite"límite
}
)
return r.json()["correos electrónicos"]
correos electrónicos = obtener_correos_de_outlook("acc_outlook_123")
para e en correos electrónicos
print(e["Asunto"], e["de"])
¿Qué es la API de Microsoft Graph para el correo electrónico?
La API de Microsoft Graph es la puerta de enlace REST unificada para todos los servicios de Microsoft 365, incluyendo correo electrónico, calendario, contactos y archivos. Específicamente para el correo electrónico, expone la /v1.0/yo/mensajes endpoint, otorgando a los desarrolladores acceso programático a todos los buzones de Outlook y Exchange. Reemplazó los protocolos heredados (autenticación básica, EWS) y ahora es la única forma oficialmente compatible de acceder al correo electrónico de Outlook de forma programática utilizando OAuth 2.0.
En Microsoft Graph API para correo electrónico ¿la interfaz RESTful expone los datos del buzón de Microsoft 365, incluidos mensajes, carpetas, archivos adjuntos y configuraciones del buzón, bajo el https://graph.microsoft.com/v1.0/me/messages endpoint. Se autentica a través de Azure Active Directory OAuth 2.0, soporta permisos delegados y de aplicación, y permite eventos en tiempo real a través de modificar suscripciones de notificación (webhooks). Es la forma recomendada de reemplazar todos los flujos de autenticación básica obsoletos.
Microsoft Graph API es la reemplazo recomendado para la Autenticación Básica obsoleta: todo el acceso al correo electrónico de Outlook y Exchange ahora requiere OAuth 2.0 a través de Graph. La autenticación básica se retiró por completo en octubre de 2022.
| Criterio | API Graph de Microsoft | SMTP / IMAP directo |
|---|---|---|
| Autenticación | OAuth 2.0 (MSAL) | Nombre de usuario + contraseña (obsoleto) |
| Límites de tarifa | 10.000 solicitudes / 10 min por aplicación | Sin límite estándar (dependiente del servidor) |
| Características | Leer, enviar, buscar, webhooks, carpetas | Limitado: solo envío/recepción básico |
| Complejidad | Flujo de OAuth + Registro de Aplicación de Azure | Baja instalación, alto mantenimiento |
| Soporte Unipile | Nativo - no se necesita flujo OAuth | Nativo - Copia de seguridad IMAP |
¿Por qué usar la API de Microsoft Graph para la integración de correo electrónico?
Desarrollar sobre Microsoft Graph te brinda acceso seguro y basado en tokens al ecosistema de correo electrónico empresarial más grande del mundo: más de 400 millones de buzones de Outlook y Exchange. Aquí están las cuatro razones principales por las que los desarrolladores eligen el punto final de correo electrónico de la API de Microsoft Graph.
Una única Solicitud de Azure cubre todas las bandejas de entrada de Outlook, Exchange y Microsoft 365. Los permisos delegados permiten que los usuarios den su consentimiento una vez; los permisos de aplicación habilitan el acceso del lado del servidor sin supervisión y sin ninguna interacción del usuario.
Lea, envíe, responda, mueva y elimine mensajes. Administre carpetas, busque en todo el buzón, maneje archivos adjuntos y configure reglas de correo, todo a través de la misma interfaz REST con un esquema de respuesta JSON predecible.
Suscríbase a las notificaciones de cambios en el buzón y reciba una solicitud HTTP POST en su endpoint cada vez que llegue un nuevo correo electrónico, se lea un mensaje o cambie una carpeta. Sin sondeos, sin demoras: eventos entregados en tiempo real.
Un único punto de conexión de API cubre cuentas personales de Outlook, inquilinos de Microsoft 365 empresariales y servidores Exchange locales (a través de híbrido). Una integración maneja todo el ecosistema de correo electrónico de Microsoft sin rutas de código separadas.
Configuración de Microsoft OAuth para la API de Outlook
Documentación de Microsoft OAuthPor defecto, tu integración utiliza las credenciales OAuth de Unipile. Para obtener una experiencia totalmente marca blanca cuando los usuarios finales conecten sus cuentas de Microsoft, cree su propia aplicación en Microsoft Entra ID. Seguir la 7 pasos a continuación para registrar tu aplicación, configurar permisos y conectarla a Unipile.
Crear una cuenta de Microsoft Entra ID
Si aún no tienes uno, crea un Microsoft Entra ID cuenta (anteriormente Azure Active Directory). Este es el portal de administración donde registrará su aplicación OAuth.
Registrar una nueva aplicación en el portal de Azure
Iniciar sesión en portal.azure.com, ir a Microsoft Entra ID, y haz clic Nuevo registro.
- Ponle nombre a tu aplicación: este nombre será visible para tus usuarios finales durante la pantalla de consentimiento de OAuth.
- Tipos de cuenta admitidos: seleccione "Cuentas en cualquier directorio de organización (cualquier Microsoft Entra ID, multitenant) y cuentas personales de Microsoft" para admitir tanto cuentas de Office 365 empresariales como personales.
Agregar URI de redireccionamiento
Ve a la Autenticación panel y clic Añadir URI en la sección Web. Agregar 2 URI de redireccionamiento usando tu DSN de Unipile (disponible en Cuadro de mandos de Unipile, arriba a la derecha):
https://{{YOUR_DSN_less_port}}/api/v1/hosted/microsoft_auth_request_callback/port{{YOUR_PORT}}
Configurar los permisos de la API
Ir a Permisos de API > Agregar un permiso > Microsoft Graph, luego añade lo siguiente Permisos delegados:
Para las funciones de calendario, añade también: Calendars.ReadWrite, Calendars.Read, Calendars.Read.Shared, Calendars.ReadWrite.Shared. Añádelas también en la configuración de ámbitos de tu Panel de Unipile.
Crear un secreto de cliente
Ir a Certificados y secretos, haga clic Nuevo secreto del cliente. Nombra el secreto y establece una fecha de caducidad de 730 días (24 meses), luego haz clic en "Añadir".
Conectarse a Unipile Dashboard
Ve a la Cuadro de mandos de Unipile, navega a Configuración > Microsoft OAuth.
- Copia y pega el ID de la aplicación (cliente) de la página Resumen de Azure.
- Pega el valor secreto de la página Certificados y secretos.
- Clic Guardar.
Probar la conexión
Desde el Panel de Unipile, active un nuevo enlace de cuenta de Microsoft para verificar que sus credenciales OAuth personalizadas funcionan correctamente. Debería ver su nombre de la aplicación y marca en el aviso de consentimiento de Microsoft en lugar de los predeterminados de Unipile.
8
Conviértete en un Editor Verificado
Recomendado para producción, elimina la advertencia "no verificado" en la pantalla de consentimiento.
Con la verificación, aparece una marca azul en el aviso de consentimiento. Sin ella, las cuentas profesionales pueden ver una advertencia de "publisher no verificado".
Paso 1: Únete a la Red de Socios de Microsoft
- Regístrate en partner.microsoft.com y elegir Programa de Socios de Microsoft AI Cloud.
- Si necesitas una cuenta de trabajo, Crear un nuevo inquilino primero.
Paso 2: Verifica tu dominio
Crear un archivo llamado microsoft-identity-association.json y alojarlo en:
Paso 3: Vincula tu ID de Cuenta Global de Partner (PGA)
- Encuentra tu ID de PGA a través de Centro de partners.
- En el Portal de Azure, ve a Registros de aplicaciones > Tu aplicación > Marca y propiedades, introduce el ID de la PGA y guarda.
Para más detalles, consulta el Documentación de verificación de Microsoft Publisher.
9
Gestionar "Se requiere aprobación del administrador"
Cuando los usuarios finales ven un bloque de consentimiento de su administrador de TI
Si un usuario ve "Se requiere la aprobación del administrador", el consentimiento requerido no ha sido otorgado a nivel de inquilino. Dos métodos para resolver esto:
Método 1: Solicitud de consentimiento del administrador en Microsoft Entra
Un administrador de Microsoft debe revisar y aprobar la solicitud de consentimiento de administrador pendiente. Ver Documentación de Microsoft sobre la revisión de solicitudes de consentimiento de administrador.
Método 2: Inicio de sesión con OAuth como administrador con consentimiento en todo el tenant
- El administrador inicia el flujo de inicio de sesión OAuth desde tu aplicación.
- Durante la autorización de Microsoft, el administrador debe marcar: "Consentimiento en nombre de su organización".
- Esto otorga el consentimiento para todos los usuarios de la organización y evita la solicitud para usuarios futuros.
Detalles completos en el Guía de solución de problemas de consentimiento de Microsoft.
Casos de uso de correo electrónico de la API de Microsoft Graph
La API de Microsoft Graph para el correo electrónico potencia una amplia gama de aplicaciones SaaS que dependen de buzones de Outlook y Exchange. Estos son los tres patrones de integración más comunes utilizados por los equipos que desarrollan en la Graph API en la actualidad.
Sincroniza hilos de correo electrónico y contactos de Outlook directamente en tu CRM. Empareja remitentes con registros de operaciones existentes, registra cada conversación automáticamente y muestra el historial de relaciones sin copiar y pegar manualmente desde Outlook.
Guía de la API de correo electrónicoRastrea hilos de correo electrónico de candidatos en buzones de Outlook. Analiza correos electrónicos de solicitud entrantes, extrae archivos adjuntos y dirígelos al canal de trabajo correcto, todo a través del punto final de correo electrónico de la API de Microsoft Graph sin intervención manual.
Enviar correo electrónico APIConvierte los correos electrónicos entrantes de Outlook en tickets de soporte. Usa webhooks de Graph para recibir eventos de nuevos correos electrónicos en tiempo real, clasifica por asunto o dominio del remitente y enruta a la cola del equipo correcto, reemplazando la clasificación manual con lógica automatizada.
API unificada de correo electrónicoCaracterísticas clave de la API de correo electrónico de Microsoft Graph
La API de Microsoft Graph para correo electrónico expone un conjunto completo de funcionalidades que van mucho más allá del envío y la recepción básicos. Aquí están las seis características más importantes que todo desarrollador debe conocer antes de crear sobre la pila de correo electrónico de la API de Microsoft Graph.
Recupera mensajes individuales o listas paginadas. Envía correos electrónicos nuevos o responde en línea. Mueve mensajes entre carpetas o márcalos como leídos/no leídos.
GET /v1.0/yo/mensajesCargar, descargar y listar archivos adjuntos en cualquier mensaje. Soporta archivos adjuntos en línea (incrustados) y cargas de archivos grandes a través de sesiones de carga para archivos de más de 3 MB.
GET /v1.0/me/messages/{id}/adjuntosCrear, renombrar y eliminar carpetas de correo. Listar todas las carpetas de correo, mover mensajes entre ellas y administrar jerarquías de carpetas secundarias, idéntico a lo que los usuarios ven en Outlook.
GET /v1.0/yo/carpetasDeCorreoUtilice parámetros de consulta OData ($filter,$search, $orderby) para buscar correos electrónicos por remitente, asunto, rango de fechas o palabra clave. Admite KQL para búsquedas avanzadas de texto completo.
GET /yo/mensajes?$buscar="proyecto"Suscríbete para recibir notificaciones de cambios en eventos del buzón. Recibe devoluciones de llamada HTTP POST casi en tiempo real cuando lleguen nuevos correos electrónicos, se lean mensajes o cambien las carpetas.
POST /v1.0/suscripcionesCombina hasta 20 solicitudes individuales de la Graph API en una única llamada HTTP usando el $punto final de lotes. Reduce drásticamente los viajes de ida y vuelta para operaciones como lecturas masivas de correo electrónico.
POST /v1.0/$loteCómo enviar, leer y sincronizar correos electrónicos con la API de Microsoft Graph
Tres patrones listos para producción que cubren las operaciones clave que todo desarrollador necesita: envío de correo electrónico, lectura de mensajes con filtros y sincronización delta incremental para monitoreo de buzón en tiempo real.
import solicita
# API Unificada de Correo Electrónico de Unipile
# Envía a través de Microsoft Graph — no se requiere OAuth directo
BASE = "https://api.unipile.com:13465/api/v1"
ENCABEZADOS = {
"Clave API X": "TU_TOKEN_DE_ACCESO",
"Tipo-Contenido": "application/json"
}
def enviar_correo_outlook(id_cuenta, para, asunto, cuerpo):
carga útil = {
"account_id": id_cuenta,
"a": [{"identificador": a}],
"Asunto": asunto,
"cuerpo"cuerpo
}
r = solicitudes.Correo electrónico:(f"{BASE}/correos", encabezados=ENCABEZADOS, json=carga útil
return r.json()
# Ejemplo de uso
enviar_correo_outlook(
"acc_outlook_123",
a="recipient@company.com",
tema="Seguimiento de la reunión",
cuerpo="Hola, dando seguimiento a nuestra llamada..."
)POST https://graph.microsoft.com/v1.0/me/sendMail con mensaje.destinatarios, mensaje.asuntoy mensaje.cuerpo.contenido. Unipile abstrae el refresco del token OAuth y el manejo MIME. Véase Guía de la API de envío de correos electrónicos para soporte de archivos adjuntos y encadenamiento de respuestas.
import solicita
# Leer correos de Outlook con filtros a través de Unipile
BASE = "https://api.unipile.com:13465/api/v1"
ENCABEZADOS = {"Clave API X": "TU_TOKEN_DE_ACCESO"}
def list_correos_outlook(id_cuenta, remitente_filtro=Ninguno, límite=20):
parámetros = {
"account_id": id_cuenta,
"límite"límite
}
si filtro_remitente:
# Mapea a $filtro=de/emailAddress/address eq '...'
parámetros["de"] = filtro_remitente
r = solicitudes.consiga(f"{BASE}/correos", encabezados=ENCABEZADOS, params=parámetros)
return r.json().obtener("artículos", [])
# Recuperar los últimos 20 correos electrónicos de un remitente específico
correos electrónicos = list_correos_outlook("acc_outlook_123", filtro_remitente="hr@acme.com")
para e en correos electrónicos
print(e["Asunto"], e["de"], e["fecha"])$filtro, $buscar, $seleccionar, $ordenar por, $superior. Usa $buscar="asunto:factura" Para la búsqueda de texto completo en KQL. Los archivos adjuntos de más de 3 MB requieren un subir sesión (POST /crearSesionDeCarga) — ni una sola solicitud de varias partes.
import solicita
# Delta Sync — solo obtener correos electrónicos NUEVOS desde la última sincronización
# Unipile maneja el ciclo de vida de deltaToken automáticamente
BASE = "https://api.unipile.com:13465/api/v1"
ENCABEZADOS = {"Clave API X": "TU_TOKEN_DE_ACCESO"}
def sincronizar_correos_nuevos(id_cuenta, cursor=Ninguno):
"""
Devuelve solo correos electrónicos recibidos desde la última llamada.
cursor = token de paginación opaco (almacenar entre llamadas).
"""
parámetros = {"account_id": id_cuenta}
si cursor
parámetros["cursor"] = cursor
r = solicitudes.consiga(f"{BASE}/correos/sincronizar", encabezados=ENCABEZADOS, params=parámetros)
datos = r.json()
return datos.obtener("artículos", []), data.get("cursor")
# Primera sincronización: sin cursor
correos, siguiente_cursor = sincronizar_correos_nuevos("acc_outlook_123")
# Almacene next_cursor en su base de datos, úselo para llamadas posteriores
print(f"{len(emails)} correos nuevos — se guardó el último cursor")GET /me/mailFolders/inbox/messages/delta devuelve un @odata.deltaLink en la primera llamada. Guárdalo y úsalo la próxima vez — Graph solo devuelve la diferencia. No hay sondeos en todos los buzones. = 10 veces menos llamadas de API que el estándar GET /mensajes. Unipile's /correos/sincronizar el punto final envuelve este patrón con gestión automática de tokens.
Webhooks de la API de Microsoft Graph para eventos de correo electrónico
Las suscripciones de Microsoft Graph (webhooks) permiten que tu servidor reciba notificaciones HTTP POST en el instante en que llega, se lee, se mueve o se elimina un correo electrónico. A continuación, se incluye un ejemplo completo en Python para suscribirse a eventos de la bandeja de entrada, además de detalles sobre la gestión del ciclo de vida.
Una suscripción de webhook de Graph tiene dos campos requeridos: cambiarTipo (qué eventos ver) y notificationUrl (tu punto de conexión HTTPS). Microsoft envía una token de validación parámetro de consulta en la primera suscripción. Tu endpoint debe devolverlo en texto plano en menos de 10 segundos para confirmar la propiedad.
Las suscripciones de graph expiran después de un máximo de 4230 minutos (~3 días) para recursos de correo. Su servidor debe renovarse antes de que expire a través de PATCH /v1.0/subscriptions/{id} o dejarás de recibir notificaciones de forma silenciosa.
Notificaciones del ciclo de vida
URL de notificación del ciclo de vida cuando una suscripción está a punto de expirar o ha sido revocada. Tu servidor debe responder con HTTP 202 para acusar recibo. El no responder provoca la terminación de la suscripción.Token de validación Handshake
?tokenDeValidación=XXX. Debes devolver el token como texto plano (Content-Type: text/plain) con HTTP 200 en menos de 10 segundos. El tiempo de espera significa que falla la creación de la suscripción.Expiración de la suscripción
fechaHoraExpiracion antes de que expire. También puedes volver a crear una suscripción desde cero. Microsoft no cobra extra por las renovaciones.import solicita, fecha y hora
TOKEN_DE_ACCESO = "TU_TOKEN_DE_GRAFICO"
PUNTO FINAL = "https://graph.microsoft.com/v1.0/subscriptions"
# Expiración: máximo 4230 min a partir de ahora para recursos de correo
caducidad = (
datetime.datetime.ahora()
+ datetime.timedelta(minutos=4200)
).isoformat() + "Z"
carga útil = {
"tipo de cambio": "creado",
"urlDeNotificación": "https://tudominio.com/webhook",
"recurso": "mis/carpetasDeCorreo('Bandeja de entrada')/mensajes",
"fechaDeExpiracion": caducidad,
"estadoCliente": "miEstadoSecreto"
}
r = solicitudes.Correo electrónico:(
PUNTO FINAL,
json=carga útil,
cabeceras={
"Autorización": "Bearer " + ACCESS_TOKEN",
"Tipo-Contenido": "application/json"
}
)
print(r.json()["id"])
# sub_xxxxxxxx-xxxx-xxxx-xxxxOmite la complejidad - Usa la API unificada de correo electrónico de Unipile
Conecta Microsoft Graph, Gmail e IMAP con un solo SDK. Sin flujos OAuth por proveedor, sin lógica de actualización de tokens, sin infraestructura de webhook que mantener. Tu equipo lanza funcionalidades de correo electrónico en días, no en semanas.
Empezar gratisNo se requiere tarjeta de crédito. Cumple con SOC 2 Tipo II.
Límites de frecuencia y manejo de errores de Microsoft Graph API
El punto final de correo electrónico de la API de Microsoft Graph aplica limitaciones en varios niveles: por usuario, por aplicación y por inquilino. Comprender estos límites antes de pasar a producción evita fallos silenciosos y degrada la fiabilidad de su integración.
Cuando Microsoft Graph se limita, devuelve HTTP 429 Demasiadas solicitudes with a Reintentar después encabezado que especifica los segundos a esperar. Siempre lea este encabezado y espere según corresponda: generar solicitudes en exceso después de un 429 extenderá la ventana de limitación, no la acortará.
| Código HTTP | Nombre del error | Causa | Arregla |
|---|---|---|---|
| 429 | Demasiadas solicitudes | Límite de velocidad excedido (10000 req / 10 min por aplicación o 1000 req / 1 min por usuario) | Leer la cabecera Retry-After. Implementar retroceso exponencial. Usar el lote $para combinar solicitudes. |
| 401 | No autorizado | Token de acceso expirado o falta el encabezado de autorización | Renovar token con MSAL. Comprobar caducidad del token antes de cada solicitud. Usar caché de tokens. |
| 403 | Prohibido | Permiso Faltante Mail.Read o Mail.Send en el Registro de Aplicaciones de Azure | Agrega los permisos de Graph requeridos en el Portal de Azure y vuelve a consentir (o consentimiento de administrador para permisos de aplicación). |
| 404 | RecursoNoEncontrado | El ID del mensaje o de la carpeta no existe (eliminado o en el inquilino equivocado) | Verifica las IDs mediante GET antes de actuar sobre ellas. Maneja el 404 cortésmente como una señal de eliminación suave. |
| 500 | Error interno del servidor | Error transitorio del servidor de Microsoft | Reintentar con retroceso exponencial (1s, 2s, 4s). Registrar la cabecera request-id para soporte de Microsoft. |
Más allá de Microsoft Graph: API unificada de correo electrónico para Gmail, Outlook e IMAP
La gestión de la integración de correo electrónico de la API de Microsoft Graph es solo el comienzo. La mayoría de los productos SaaS deben admitir Gmail, Outlook e IMAP simultáneamente, lo que significa tres flujos de OAuth separados, tres bucles de actualización de tokens y tres sistemas de webhook. Unipile's API de correo electrónico unificada abstrae a los tres proveedores detrás de un solo punto de acceso.
API de Gmail
Microsoft Graph
IMAP / SMTP
Con Unipile's integración unificada de API de correo electrónico, escribes una integración y soportas instantáneamente los tres tipos de proveedores. Unipile gestiona las cuentas vinculadas: tu backend solo habla con un endpoint REST independientemente de si el buzón del usuario funciona con Microsoft Graph, Gmail o IMAP.
No hay flujos de OAuth para gestionar Unipile se encarga de la adquisición, actualización y revocación de tokens para Microsoft Graph y Gmail en tu nombre.
Eventos unificados de webhook - notificationUrl recibe eventos de correo electrónico de todos los proveedores con un esquema JSON normalizado. Sin gestión de suscripciones por proveedor.
Cumple con SOC 2 Tipo II - todos los datos de correo electrónico en tránsito están cifrados. Unipile no almacena contenido de correo electrónico más allá de lo que requiere su integración.
Empieza a integrar el correo electrónico de Microsoft Graph en minutos
Únete a más de 200 equipos de SaaS que usan Unipile para conectar Outlook, Gmail e IMAP bajo una sola API. Sin dependencia del proveedor. Cumple con SOC 2.
Preguntas frecuentes
Todo lo que los desarrolladores preguntan antes de crear en el punto final de correo electrónico de la API de Microsoft Graph: desde la autenticación hasta los límites de frecuencia y la cobertura del proveedor.
https://graph.microsoft.com/v1.0/me/messages y utiliza autenticación OAuth 2.0 a través de Azure Active Directory. Admite la lectura, el envío, la búsqueda y la gestión de correos electrónicos, así como la recepción de notificaciones de cambios en tiempo real a través de suscripciones de webhook./v1.0/suscripciones with a cambiarTipo (por ejemplo, "creado"), un notificationUrl apuntando a tu punto de conexión HTTPS, y un recurso (por ejemplo, "me/mailFolders('Inbox')/messages"). Microsoft envía inmediatamente una solicitud GET con un token de validación - su servidor debe reflejarlo como texto plano en 10 segundos. Las suscripciones expiran después de un máximo de 4230 minutos y deben renovarse mediante PATCH antes de su vencimiento.
ES 
EN 
FR 
DE 
IT 
BR 
NL 
PL 
TR