Переход с 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.