Миграция с API настроек электронной почты

В этом документе описаны ключевые различия между API настроек электронной почты и API Gmail. Вы можете использовать это руководство, чтобы перенести свое приложение на API Gmail.

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

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

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"
}

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

Управление ярлыками

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

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

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

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

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

Для управления фильтрами в API Gmail используйте ресурс «Фильтры» .

Старая настройка Новая настройка Примечания
от критерии.из
к критерии.to
предмет критерии.предмет
имеетTheWord критерии.запрос
DoNotHaveTheWord критерии.negatedQuery
hasAttachment критерии.hasAttachment
следуетАрхивировать action.removeLabelIds Используйте INBOX в качестве идентификатора ярлыка.
следуетОтметить как прочитанное action.removeLabelIds Используйте UNREAD в качестве идентификатора ярлыка.
долженStar action.addLabelIds Используйте STARRED в качестве идентификатора ярлыка.
этикетка action.addLabelIds Используйте идентификатор ярлыка, чтобы добавить
впередTo действие.вперед
следуетКорзина action.addLabelIds Используйте TRASH в качестве идентификатора ярлыка.
никогдаСпам action.removeLabelIds Использовать SPAM в качестве идентификатора ярлыка

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

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

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

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

Старая настройка Новая настройка
имя отображаемое имя
адрес ОтправитьКакЭлектронная почта
ОтветитьКому ответить на адрес
makeDefault isDefault

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

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

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

Для управления автопересылкой в ​​Gmail API используйте ресурс «Настройки» .

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

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

  • Адреса пересылки должны быть созданы и проверены перед использованием.
  • Адресами пересылки можно управлять с помощью ресурса ForwardingAddresses .

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

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

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

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

Чтобы управлять доступом по IMAP в Gmail API, используйте ресурс «Настройки» .

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

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

Чтобы управлять автоответом на отпуск в API Gmail, используйте ресурс «Настройки» .

Старая настройка Новая настройка
только контакты ОграничитьToContacts
ДоменТолько ОграничитьToDomain
давать возможность включитьавтоответчик
КонечнаяДата время окончания
сообщение тело ответаHtml
ответBodyPlainText
Дата начала время начала
предмет ответТема

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

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

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

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

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

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

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

Старая настройка Новая настройка
язык дисплейЯзык

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

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

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

Старая настройка Новая настройка
адрес делегатЭлектронная почта
статус статус проверки

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

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

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

Общие настройки больше не доступны через API.