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

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

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

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

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 используйте ресурс «Ярлыки» .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Старая обстановка Новая обстановка
КонтактыТолько restrictToContacts
только домен restrictToDomain
давать возможность включитьАвтоответ
Дата окончания время окончания
сообщение responseBodyHtml
responseBodyPlainText
Дата начала время начала
предмет ответТема

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

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

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

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

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

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

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

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

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

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

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

Старая обстановка Новая обстановка
адрес делегатEmail
статус статус проверки

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

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

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

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