Переход с API настроек электронной почты

Этот документ поможет вам перевести ваше приложение с устаревшего API настроек электронной почты на API Gmail.

Авторизация запросов

Как и API настроек электронной почты, API Gmail использует протокол OAuth 2.0 для авторизации запросов. Ключевое отличие заключается в том, что разрешения API Gmail ограничены конкретным пользователем, а не всем доменом. Это означает, что авторизация учетной записи администратора домена не позволяет переносить почту для других пользователей в домене. Вместо этого необходимо использовать стандартные служебные учетные записи с полномочиями для всего домена , которые добавлены в список разрешенных в консоли администратора Google, для генерации соответствующего токена аутентификации.

API настроек электронной почты использовал следующую область действия:

https://apps-apis.google.com/a/feeds/emailsettings/2.0/

В API Gmail эквивалентными областями видимости являются:

https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing

Изменения протокола

API настроек электронной почты использует протокол GDATA на основе XML. API Gmail использует JSON. Поскольку настройки в основном состоят из пар ключ-значение, полезные данные концептуально схожи между версиями.

Пример создания метки:

API настроек электронной почты 

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 Gmail 

POST https://www.googleapis.com/gmail/v1/users/{username}/labels
{
   "name": "status updates"
}

Используйте предоставленные клиентские библиотеки вместо непосредственной реализации протокола.

Управление метками

Для управления метками в API Gmail используйте ресурс labels .

Старая обстановка Новая настройка Примечания
labelId идентификатор
этикетка имя
unreadCount непрочитанные сообщения
видимость labelListVisibility SHOW теперь называется labelShow
HIDE теперь называется labelHide

Другие изменения:

  • При обновлении или удалении меток API Gmail обращается к меткам по идентификатору, а не по имени.

Управление фильтрами

Для управления фильтрами в API Gmail используйте ресурс settings.filters .

Старая обстановка Новая настройка Примечания
от критерии.из
к критерии.to
предмет критерии.субъект
hasTheWord критерии.запрос
doesNotHaveTheWord criteria.negatedQuery
имеетВложение criteria.hasAttachment
shouldArchive action.removeLabelIds Используйте INBOX в качестве идентификатора метки.
shouldMarkAsRead action.removeLabelIds Используйте UNREAD в качестве идентификатора метки.
shouldStar action.addLabelIds Используйте STARRED в качестве идентификатора метки.
этикетка action.addLabelIds Используйте идентификатор метки для добавления.
forwardTo действие.вперед
shouldTrash action.addLabelIds Используйте TRASH в качестве идентификатора метки.
neverSpam action.removeLabelIds Используйте SPAM в качестве идентификатора метки.

Другие изменения:

  • Если метка пользователя еще не существует, ее необходимо явно создать с помощью метода labels.create .

Управление псевдонимами для отправки

Для управления псевдонимами для отправки сообщений в API Gmail используйте ресурс settings.sendAs .

Старая обстановка Новая настройка
имя отображаемое имя
адрес sendAsEmail
ответить replyToAddress
makeDefault isDefault

Управление веб-клипами

Настройки веб-клипов недоступны в API Gmail.

Управление автоматической пересылкой

Для управления автоматической пересылкой почты через API Gmail используйте ресурс settings .

Старая обстановка Новая настройка Примечания
давать возможность включено
forwardTo Адрес электронной почты
действие расположение KEEP теперь называется leaveInInbox
ARCHIVE теперь называется archive
DELETE теперь — trash
MARK_READ теперь равно markRead

Другие изменения:

  • Адреса переадресации необходимо создать и проверить до начала использования.
  • Адреса переадресации можно настроить с помощью ресурса settings.forwardingAddresses .

Управление настройками POP

Для управления доступом по протоколу POP в API Gmail используйте ресурс settings .

Старая обстановка Новая настройка Примечания
давать возможность доступное окно Отключается, если установлено disabled
enableFor доступное окно ALL_MAIL теперь называется allMail
MAIL_FROM_NOW_ON теперь fromNowOn
действие расположение KEEP теперь называется leaveInInbox
ARCHIVE теперь называется archive
DELETE теперь — trash
MARK_READ теперь равно markRead

Управление настройками IMAP

Для управления доступом по протоколу IMAP в API Gmail используйте ресурс settings .

Старая обстановка Новая настройка
давать возможность включено

Управление настройками автоматического ответа во время отпуска

Для управления автоматическими ответами на письма во время отпуска в API Gmail используйте ресурс settings .

Старая обстановка Новая настройка
только контакты restrictToContacts
domainOnly restrictToDomain
давать возможность включить автоответ
конечная дата endTime
сообщение responseBodyHtml
responseBodyPlainText
Дата начала startTime
предмет ответСубъект

Управление настройками подписи

Для управления подписями в электронных письмах через API Gmail используйте ресурс settings.sendAs .

Старая обстановка Новая настройка
подпись подпись

Другие изменения:

  • Теперь подписи управляются по псевдонимам.

Управление языковыми настройками

Для управления языковыми настройками в API Gmail используйте ресурс settings .

Старая обстановка Новая настройка
язык displayLanguage

Для получения дополнительной информации см. раздел «Управление языковыми настройками» .

Управление настройками делегирования

Для управления делегированием в API Gmail используйте ресурс settings.delegates .

Старая обстановка Новая настройка
адрес delegateEmail
статус статус проверки

Другие изменения:

  • Общий
    • Для использования любого из методов делегирования (включая settings.delegates.create ) пользователь-делегат должен быть включен в Gmail. Это означает, например, что пользователя-делегата нельзя заблокировать в Google Workspace.
    • Для новых методов в качестве адреса электронной почты делегата нельзя использовать псевдоним. На пользователя-делегата необходимо указывать его основной адрес электронной почты.
  • settings.delegates.create
    • Теперь этот метод можно использовать для создания делегированных связей между несколькими доменами, принадлежащими одной и той же организации Google Workspace.
    • Теперь этот метод можно использовать для пользователей, которым требуется смена пароля при следующем входе в систему.
    • В случае успеха этот метод возвращает ресурс settings.delegates в теле ответа, а не пустое тело ответа.
    • Если один из пользователей, делегирующих или делегирующих задачу, отключен (например, приостановлен в Google Workspace), этот метод завершится ошибкой HTTP 4XX вместо ошибки HTTP 500.
  • settings.delegates.delete
    • Теперь этот метод можно использовать для удаления делегатов с любым VerificationStatus , а не только делегатов, которые были accepted или expired .
  • settings.delegates.get
    • Это новый метод, который в зависимости от потребностей может быть предпочтительнее метода settings.delegates.list .

Управление общими настройками

Общие настройки недоступны в API Gmail.