En este documento, se describen las diferencias clave entre la API de Email Settings y la API de Gmail. Puedes usar esta guía para migrar tu app a la API de Gmail.
Autorizar solicitudes
Al igual que la API de Email Settings, la API de Gmail usa el protocolo OAuth 2.0 para autorizar solicitudes. Una diferencia clave es que los permisos de la API de Gmail se limitan a un usuario individual, en lugar de a todo el dominio. Esto significa que autorizar una cuenta de administrador de dominio no te permite migrar el correo electrónico de otros usuarios en el dominio. En su lugar, debes usar cuentas de servicio estándar con autoridad en todo el dominio que estén incluidas en la lista blanca de la Consola del administrador para generar el token de autenticación adecuado.
La API de Email Settings usó el permiso:
https://apps-apis.google.com/a/feeds/emailsettings/2.0/
Los permisos equivalentes en la API de Gmail son los siguientes:
https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing
Cambios de protocolo
La API de Email Settings usa el protocolo GDATA basado en XML. La API de Gmail usa JSON. Dado que la configuración se compone principalmente de pares clave-valor, las cargas útiles son similares de forma conceptual entre las versiones.
Ejemplo de creación de una etiqueta:
API de configuración de correo electrónico
POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain name}/{username}/label
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name="label" value="status updates" />
</atom:entry>
API de Gmail
POST https://www.googleapis.com/gmail/v1/users/{username}/labels
{
"name": "status updates"
}
Usa las bibliotecas cliente proporcionadas en lugar de implementar directamente el protocolo.
Administra etiquetas
Para administrar etiquetas en la API de Gmail, usa el recurso Etiquetas.
| Configuración anterior | Configuración nueva | Notas |
|---|---|---|
| labelId | id | |
| etiqueta | name | |
| unreadCount | messagesUnread | |
| visibilidad | labelListVisibility | SHOW ahora es labelShowHIDE ahora es labelHide |
Otros cambios:
- Cuando actualizas o borras etiquetas, la API de Gmail hace referencia a las etiquetas por ID en lugar de por nombre.
Administra filtros
Para administrar filtros en la API de Gmail, usa el recurso Filtros.
| Configuración anterior | Configuración nueva | Notas |
|---|---|---|
| de | criteria.from | |
| para | criteria.to | |
| asunto | criteria.subject | |
| hasTheWord | criteria.query | |
| doesNotHaveTheWord | criteria.negatedQuery | |
| hasAttachment | criteria.hasAttachment | |
| shouldArchive | action.removeLabelIds | Usa INBOX como el ID de etiqueta. |
| shouldMarkAsRead | action.removeLabelIds | Usa UNREAD como el ID de etiqueta. |
| shouldStar | action.addLabelIds | Usa STARRED como el ID de etiqueta. |
| etiqueta | action.addLabelIds | Usa el ID de la etiqueta para agregarla |
| forwardTo | action.forward | |
| shouldTrash | action.addLabelIds | Usa TRASH como el ID de etiqueta. |
| neverSpam | action.removeLabelIds | Usa SPAM como el ID de etiqueta. |
Otros cambios:
- Si agregar una etiqueta de usuario aún no existe, debe crearse de forma explícita con el método labels.create.
Administra alias de envío
Si quieres administrar los alias de envío en la API de Gmail, usa el recurso SendAs.
| Configuración anterior | Configuración nueva |
|---|---|
| name | displayName |
| de la página web. | sendAsEmail |
| replyTo | replyToAddress |
| makeDefault | isDefault |
Administración de clips web
La configuración de Web Clip ya no está disponible a través de la API.
Administra la configuración de reenvío automático
Para administrar el reenvío automático en la API de Gmail, usa el recurso Configuración.
| Configuración anterior | Configuración nueva | Notas |
|---|---|---|
| enable | habilitado | |
| forwardTo | emailAddress | |
| acción | disposition | KEEP ahora es leaveInInboxARCHIVE ahora es archiveDELETE ahora es trashMARK_READ ahora es markRead |
Otros cambios:
- Se deben crear y verificar las direcciones de reenvío antes de utilizarlas
- Las direcciones de reenvío se pueden administrar a través del recurso ForwardingAddresses.
Administrar la configuración de POP
Para administrar el acceso POP en la API de Gmail, usa el recurso Configuración.
| Configuración anterior | Configuración nueva | Notas |
|---|---|---|
| enable | accessWindow | Inhabilitado cuando se establece en disabled |
| enableFor | accessWindow | ALL_MAIL ahora es allMailMAIL_FROM_NOW_ON ahora es fromNowOn |
| acción | disposition | KEEP ahora es leaveInInboxARCHIVE ahora es archiveDELETE ahora es trashMARK_READ ahora es markRead |
Administración de la configuración de IMAP
Para administrar el acceso de IMAP en la API de Gmail, usa el recurso de Configuración.
| Configuración anterior | Configuración nueva |
|---|---|
| enable | habilitado |
Cómo administrar la configuración de respuesta automática de vacaciones
Para administrar la respuesta automática automática en la API de Gmail, usa el recurso Configuración.
| Configuración anterior | Configuración nueva |
|---|---|
| contactsOnly | restrictToContacts |
| domainOnly | restrictToDomain |
| enable | enableAutoReply |
| endDate | endTime |
| message | responseBodyHtml responseBodyPlainText |
| startDate | startTime |
| asunto | responseSubject |
Administración de la configuración de firma
Para administrar las firmas de correo electrónico en la API de Gmail, usa el recurso SendAs.
| Configuración anterior | Configuración nueva |
|---|---|
| firma | firma |
Otros cambios:
- Las firmas ahora se administran por alias.
Administra la configuración de idioma
Para administrar la configuración de idioma en la API de Gmail, usa el recurso Configuración.
| Configuración anterior | Configuración nueva |
|---|---|
| language | displayLanguage |
Consulta la guía de administración de la configuración de idioma para obtener más información.
Administrar la configuración de delegación
Para administrar la delegación en la API de Gmail, usa el recurso Delegados.
| Configuración anterior | Configuración nueva |
|---|---|
| de la página web. | delegateEmail |
| status | verificationStatus |
Otros cambios:
- General
- Para usar cualquiera de los métodos de delegación (incluido delegates.create), el usuario encargado de delegar debe estar habilitado para Gmail. Eso significa, por ejemplo, que el usuario encargado de delegar no se puede suspender enGoogle Workspace.
- No se puede usar un alias de correo electrónico como entrada de correo electrónico delegada para ninguno de los métodos nuevos. Se debe hacer referencia a un usuario delegado por su dirección de correo electrónico principal.
- delegates.create
- Ahora se puede usar este método para crear relaciones delegadas entre varios dominios que pertenecen a la misma Google Workspaceorganización.
- Ahora, este método se puede usar para los usuarios que requieren un cambio de contraseña la próxima vez que accedan.
- Si se aplica correctamente, este método muestra un recurso Users.settings.delegates en el cuerpo de la respuesta, en lugar de un cuerpo de respuesta vacío.
- Si alguno de los usuarios delegados o delegados está inhabilitado (por ejemplo, suspendido en Google Workspace), este método falla con un error HTTP 4XX en lugar de HTTP 500.
- delegates.delete
- Ahora se puede usar este método para borrar delegados con cualquier verificationStatus, en lugar de solo los delegados que sean
acceptedoexpired.
- Ahora se puede usar este método para borrar delegados con cualquier verificationStatus, en lugar de solo los delegados que sean
- delegates.get
- Este es un método nuevo, que puede ser preferible al método delegates.list según sea necesario.
Cómo administrar la configuración general
La configuración general ya no está disponible a través de la API.