Información general para usar las API de REST de Outlook

  • Artículo

Sugerencia

Pruebe a usar las llamadas de REST de ejemplo en el Probador de Graph. Puede usar su propia cuenta o una de nuestras cuentas de prueba. Cuando termine de explorar la API, vuelva aquí y seleccione su plataforma favorita a la izquierda. Le guiaremos por los pasos necesarios para escribir una aplicación sencilla con la que recuperar mensajes de la bandeja de entrada.

Si la plataforma de su elección no figura, continúe leyendo esta página. Realizaremos el mismo conjunto de pasos, pero con solicitudes HTTP sin procesar.

El propósito de esta guía consiste en detallar el proceso necesario para llamar a la API de Correo de Outlook para recuperar mensajes de correo electrónico en Office 365 y Outlook.com. A diferencia de las guías de introducción específicas de cada plataforma, esta guía se centra en las solicitudes y respuestas OAuth y REST. Cubrirá la secuencia de solicitudes y respuestas que una aplicación usa para autenticar y recuperar mensajes.

En este tutorial usaremos Microsoft Graph para llamar a la API de correo. Microsoft recomienda usar Microsoft Graph para tener acceso al correo, al calendario y a los contactos de Outlook. Las API de Outlook se deben usar directamente (a través de https://outlook.office.com/api) solo en caso de que se necesite una característica que no esté disponible en los extremos de Graph.

Con la información de esta guía, podrá implementar esto en cualquier lenguaje o plataforma capaz de enviar solicitudes HTTP.

Usar OAuth2 para autenticar

Para llamar a la API de correo, la aplicación requiere un token de acceso de la Plataforma de identidad de Microsoft. Use uno de los flujos de OAuth 2.0 compatibles para obtener un token de acceso.

Llamar a la API de correo

Cuando la aplicación tenga un token de acceso, estará lista para llamar a la API de correo. En el tema de referencia de la API de correo encontrará todos los detalles. Como la aplicación está recuperando mensajes, usará una solicitud HTTP GET enviada la dirección URL https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages. Esto hará que se recuperen los mensajes de la bandeja de entrada.

Refinar la solicitud

Las aplicaciones pueden controlar el comportamiento de las solicitudes GET usando parámetros de consulta de OData. Se recomienda que las aplicaciones usen estos parámetros para limitar tanto el número de resultados que se devuelven como los campos que se devuelven en relación con cada elemento. Veamos un ejemplo.

Imaginemos una aplicación que muestra mensajes en una tabla. La tabla muestra solamente el asunto, el remitente y la fecha y la hora en que se recibió el mensaje. Esta tabla contiene un máximo de 25 filas y debe estar ordenada de forma que los mensajes recibidos más recientemente estén al principio.

Para lograrlo, la aplicación usa los siguientes parámetros de consulta:

  • El parámetro $select se usa para especificar solo los campos subject, from y receivedDateTime.
  • El parámetro $top se usa para especificar un máximo de 25 elementos.
  • El parámetro $orderby se usa para ordenar los resultados.por el campo de receivedDateTime.

Esto da como resultado la siguiente solicitud.

Solicitud de la API de correo para los mensajes en la bandeja de entrada

GET https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$select=subject,from,receivedDateTime&$top=25&$orderby=receivedDateTime%20DESC

Accept: application/json
Authorization: Bearer eyJ0eXAi...b66LoPVA

Respuesta de la API de correo

HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(...)/mailfolders('inbox')messages(subject,from,receivedDateTime)",
  "value": [
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABufX4i\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABufW1UAAA=",
      "subject": "Ruby on Rails tutorial",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2015-01-29T20:44:53Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABSzmz4\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABMirSeAAA=",
      "subject": "Trip Information",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-12-09T21:55:41Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABzxiLG\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABAblZoAAA=",
      "subject": "Multiple attachments",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-11-19T20:35:59Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAAA9yBBa\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAAA9x_8YAAA=",
      "subject": "Attachments",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-11-18T20:38:43Z"
    }
  ]
}

Ahora que ya hemos visto cómo realizar llamadas a la API de correo, puede usar la referencia de la API para construir cualquier otro tipo de llamada que la aplicación necesite realizar. Con todo, tenga en cuenta que la aplicación debe tener los permisos adecuados configurados en el registro de aplicaciones para las llamadas que realice.