Resumen de la API de Gmail

La API de Gmail es una API RESTful que se puede utilizar para acceder a los buzones de correo de Gmail y enviar correo. Para la mayoría de las aplicaciones web (incluidas las aplicaciones móviles), la API de Gmail es la mejor opción para el acceso autorizado a los datos de Gmail de un usuario.

La API de Gmail ofrece un acceso flexible y RESTful a la bandeja de entrada del usuario, con una interfaz natural paraThreads,Messages,Labels,Drafts,History, y.Settings.Desde el lenguaje moderno que elijas, tu aplicación puede utilizar la API para añadir funciones deGmail como:

• Leer mensajes de Gmail
• Enviar mensajes de correo electrónico
• Modificar las etiquetas aplicadas a los mensajes e hilos
• Buscar mensajes e hilos específicos
• Crear filtros para etiquetar automáticamente, reenviar o archivar mensajes

Todo lo que necesitas para utilizar la API de Gmail es la biblioteca del cliente para el idioma que elijas y una aplicación que pueda autenticarse como usuario de Gmail.

Casos de uso típicos

La API de Gmail se puede utilizar en una gran variedad de aplicaciones diferentes, entre las que se incluyen, normalmente:

• Extracción de correo de sólo lectura, indexación y copia de seguridad
• Gestión de etiquetas (añadir/eliminar etiquetas)
• Envío de mensajes automatizado o programado
• Migrar cuentas de correo electrónico de otros proveedores
• Establecer firmas de correo electrónico estandarizadas para los usuarios de un dominio

¿Cómo puedo obtener más información?

Usa esta documentación para empezar a crear una aplicación de Gmail hoy mismo:

• Las bibliotecas de cliente están disponibles para su descarga en varios idiomas y simplifican la realización de solicitudes a la API.
• Los temas de la guía para desarrolladores te ayudan a entender mejor cómo implementar casos de uso particulares.
• La referencia de la API ofrece detalles sobre cada recurso y método de la API de Gmail.

Resumen de la API

La API de Gmail es un servicio web: utiliza una API RESTful con una carga útil JSON. Para obtener información detallada sobre los recursos y los métodos de la API, consulta la referencia de GmailAPI.

Tipos de recursos clave

La API de Gmail proporciona varios tipos de recursos:

• Mensajes
• Etiquetas
• Borradores
• Historia
• Hilos
• Configuración

Los mensajes y las etiquetas son las unidades básicas de un buzón. Los borradores, el historial y los hilos contienen uno o más mensajes con metadatos adicionales.

Los mensajes son inmutables: sólo se pueden crear y eliminar. No se pueden cambiar las propiedades de los mensajes, salvo las etiquetas aplicadas a un mensaje determinado.

Las etiquetas sirven como medio principal para categorizar y organizar los mensajes y los hilos. Una etiqueta tiene una relación de muchos a muchos con los mensajes e hilos: un solo mensaje puede tener varias etiquetas aplicadas y una sola etiqueta puede aplicarse a varios mensajes o hilos. Las etiquetas también son de dos tipos: system y user. Las etiquetas del sistema, como INBOX, TRASH o SPAM, se crean internamente y no pueden crearse, borrarse o modificarse. Sin embargo, algunas etiquetas del sistema, como INBOX, pueden aplicarse o eliminarse de los mensajes y los hilos. Las etiquetas de usuario pueden ser añadidas, eliminadas o modificadas por el usuario o una aplicación.

Los borradores representan mensajes no enviados. Los mensajes en sí no pueden ser modificados una vez creados, pero el mensaje contenido en el borrador puede ser reemplazado.El envío de un borrador elimina automáticamente el borrador y crea un mensaje con la etiqueta del sistema SENT.

El historial es una colección de mensajes modificados recientemente en orden cronológico.Aunque el historial está pensado como un método ligero de sincronización de un cliente, normalmente sólo contiene registros de los cambios en los últimos 30 días. En algunos casos, como cuando un cliente se desactualiza demasiado, el cliente debería sincronizarse manualmente.

Los hilos son colecciones de mensajes que representan una conversación. Al igual que los mensajes, los hilos también pueden tener etiquetas aplicadas. Sin embargo, a diferencia de los mensajes, los hilos no pueden ser creados, sólo eliminados. Sin embargo, los mensajes pueden insertarse en un hilo.

La configuración controla el comportamiento de las funciones de Gmail para un usuario. La configuración está disponible para el acceso POP e IMAP, el reenvío de correo electrónico, los filtros, la respuesta automática de vacaciones, los alias de envío, las firmas, los delegados y el idioma.

Auth y la API de Gmail

Al igual que otras API REST de Google, la API de Gmail utiliza OAuth 2.0 para gestionar la autenticación y la autorización. Tu aplicación especificará uno o varios ámbitos: cadenas que identifican los recursos a los que necesita acceder. Estos ámbitos se utilizan junto con un conjunto de tokens para asegurar el acceso de un usuario a los recursos.Un ámbito representa una forma particular de acceso a un solo recurso o a un grupo de recursos, por ejemplo:

• Leer un mensaje de Gmail (https://www.googleapis.com/auth/gmail.readonly)
• Cambiar las etiquetas aplicadas a un hilo o a un mensaje(https://www.googleapis.com/auth/gmail.modify)
• Enviar un mensaje en nombre de un usuario(https://www.googleapis.com/auth/gmail.compose)

Aunque puedes codificar las llamadas de autorización del servicio web explícitamente, normalmente deberías simplificar tu aplicación utilizando las bibliotecas de cliente de la API de Google disponibles para muchos lenguajes de programación.

Para obtener más información sobre el uso de auth con la API de Gmail, consultaAutorización de tu aplicación con Gmail.

Escopios

La API de Gmail admite una serie de ámbitos de autorización de grano fino para permitir sólo el nivel de acceso necesario. Al solicitar el nivel mínimo de acceso necesario, los usuarios se sienten más seguros a la hora de conceder acceso a su buzón de correo.

Ejemplo de uso

Considera el siguiente caso de uso: imprimir una página de hilos para el usuario actualmente autenticado (por ejemplo, en un panel de mensajes recientes).Para lograrlo, tu aplicación realizaría los siguientes pasos:

1. Autenticarse como el usuario, utilizando el ámbitohttps://www.googleapis.com/auth/gmail.readonly.
2. Llamar al método de la API.GET https://www.googleapis.com/gmail/v1/users/<userId>/threads
3. Procesar la lista de hilos devuelta en su aplicación.

Para el código de ejemplo real, consulte el Quickstart para el lenguaje de su elección.

Usos comunes

Esta sección proporciona una visión de muy alto nivel de cómo algunos casos de uso comunes pueden ser implementados. Para obtener más detalles, consulte las guías para desarrolladores.

Envío de mensajes de Gmail

Los mensajes de correo electrónico se envían como cadenas codificadas con base64url dentro de la propiedad rawde un mensaje. Para crear y enviar un mensaje:

1. Cree el contenido del correo electrónico de alguna manera conveniente, que puede depender del lenguaje de programación que esté utilizando.
2. Cree una representación de cadena codificada en base64url de ese contenido.
3. Crea un nuevo recurso messager y establece su propiedad raw a la cadena base64url que acabas de crear.
4. Llama a messages.sendpara enviar el mensaje.

Obtención de correos electrónicos recibidos

Dado el ID de un correo electrónico, puedes obtener el contenido utilizando el métodogetdel recurso Users.messages.

Cuando se obtiene un mensaje, se puede especificar el formato de la carga útil de la respuesta.FULL (el predeterminado) devuelve todo el mensaje analizado en el campo payload.MINIMALEl formato devuelve sólo los metadatos, como los identificadores y las etiquetas.RAWEl formato devuelve los datos como una cadena codificada en base64url dentro de la propiedad raw.

Historial de cambios en el correo

Los cambios en los mensajes se representan medianteHistory objects. La propiedadstart_history_id le permite establecer desde qué punto quiere que se devuelvan los cambios. Algunos cambios pueden afectar a más de un mensaje y, por lo tanto, el historial que representa ese cambio contendrá varios mensajes.

Gestión de etiquetas

Las etiquetas aplicadas a un hilo también se aplican a todos los mensajes dentro del hilo.Si se borra una etiqueta, se elimina de todos los hilos y mensajes a los que se aplicó. La propiedad messageListVisibility se utiliza para determinar si los mensajes con esta etiqueta aparecen en la lista de mensajes. Del mismo modo, la propiedadlabelListVisibility se utiliza para determinar si la etiqueta aparece en la lista de etiquetas. Puede utilizar el métodomessages.modify othreads.modify para cambiar las etiquetas aplicadas a los mensajes o a los hilos, respectivamente.