Bermigrasi dari Email Settings API

Dokumen ini membahas perbedaan utama antara Email Settings API dan Gmail API. Anda dapat menggunakan panduan ini untuk membantu memigrasikan aplikasi ke Gmail API.

Mengotorisasi permintaan

Seperti Email Settings API, Gmail API menggunakan protokol OAuth 2.0 untuk memberi otorisasi pada permintaan. Satu perbedaan utama adalah izin Gmail API dibatasi untuk setiap pengguna, bukan untuk seluruh domain. Artinya, memberi otorisasi ke akun administrator domain tidak memungkinkan Anda memigrasikan email untuk pengguna lain di domain. Sebagai gantinya, Anda harus menggunakan akun layanan standar dengan otoritas tingkat domain yang diizinkan di konsol Admin untuk membuat token autentikasi yang sesuai.

Email Settings API menggunakan cakupan:

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

Cakupan yang setara di Gmail API adalah:

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

Perubahan protokol

Email Settings API menggunakan protokol GDATA berbasis XML. Gmail API menggunakan JSON. Karena setelan sebagian besar terdiri dari pasangan kunci/nilai, payload secara konsep serupa antarversi.

Contoh pembuatan label:

Email Settings 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>

Gmail API

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

Gunakan Library klien yang disediakan, bukan langsung menerapkan protokol.

Mengelola label

Untuk mengelola label di Gmail API, gunakan resource Labels.

Setelan lama Setelan baru Catatan
labelId id
label nama
unreadCount messagesUnread
visibilitas labelListVisibility SHOW kini menjadi labelShow
HIDE kini menjadi labelHide

Perubahan lainnya:

  • Saat memperbarui atau menghapus label, Gmail API mereferensikan label menurut ID, bukan menurut nama.

Mengelola filter

Untuk mengelola filter di Gmail API, gunakan resource Filters.

Setelan lama Setelan baru Catatan
dari criteria.from
hingga criteria.to
subjek criteria.subject
hasTheWord criteria.query
doesNotHaveTheWord criteria.negatedQuery
hasAttachment criteria.hasAttachment
shouldArchive action.removeLabelIds Menggunakan INBOX sebagai ID label
shouldMarkAsRead action.removeLabelIds Menggunakan UNREAD sebagai ID label
shouldStar action.addLabelIds Menggunakan STARRED sebagai ID label
label action.addLabelIds Gunakan ID label untuk menambahkan
forwardTo action.forward
shouldTrash action.addLabelIds Menggunakan TRASH sebagai ID label
neverSpam action.removeLabelIds Menggunakan SPAM sebagai ID label

Perubahan lainnya:

  • Jika belum ada, label pengguna harus dibuat secara eksplisit menggunakan metode labels.create.

Mengelola alias kirim sebagai

Untuk mengelola alias send-as di Gmail API, gunakan resource SendAs.

Setelan lama Setelan baru
nama Nama Tampilan
alamat sendAsEmail
replyTo replyToAddress
makeDefault isDefault

Mengelola klip web

Setelan Web Clip tidak lagi tersedia melalui API.

Mengelola setelan penerusan otomatis

Untuk mengelola penerusan otomatis di Gmail API, gunakan resource Setelan.

Setelan lama Setelan baru Catatan
aktifkan diaktifkan
forwardTo emailAddress
action disposisi KEEP kini menjadi leaveInInbox
ARCHIVE kini menjadi archive
DELETE kini menjadi trash
MARK_READ kini menjadi markRead

Perubahan lainnya:

  • Alamat penerusan harus dibuat dan diverifikasi sebelum digunakan
  • Alamat penerusan dapat dikelola melalui resource ForwardingAddresses.

Mengelola setelan POP

Untuk mengelola akses POP di Gmail API, gunakan resource Setelan.

Setelan lama Setelan baru Catatan
aktifkan accessWindow Dinonaktifkan jika disetel ke disabled
enableFor accessWindow ALL_MAIL kini menjadi allMail
MAIL_FROM_NOW_ON kini menjadi fromNowOn
action disposisi KEEP kini menjadi leaveInInbox
ARCHIVE kini menjadi archive
DELETE kini menjadi trash
MARK_READ kini menjadi markRead

Mengelola setelan IMAP

Untuk mengelola akses IMAP di Gmail API, gunakan resource Setelan.

Setelan lama Setelan baru
aktifkan diaktifkan

Mengelola setelan balasan otomatis saat libur

Untuk mengelola balasan otomatis saat libur di Gmail API, gunakan resource Setelan.

Setelan lama Setelan baru
contactsOnly restrictToContacts
domainOnly restrictToDomain
aktifkan enableAutoReply
endDate endTime
pesan responseBodyHtml
responseBodyPlainText
startDate startTime
subjek responseSubject

Mengelola setelan tanda tangan

Untuk mengelola tanda tangan email di Gmail API, gunakan resource SendAs.

Setelan lama Setelan baru
tanda tangan tanda tangan

Perubahan lainnya:

  • Tanda tangan kini dikelola per alias.

Mengelola setelan bahasa

Untuk mengelola setelan bahasa di Gmail API, gunakan resource Setelan.

Setelan lama Setelan baru
language displayLanguage

Silakan baca panduan Mengelola Setelan Bahasa untuk informasi selengkapnya.

Mengelola setelan delegasi

Untuk mengelola delegasi di Gmail API, gunakan resource Delegates.

Setelan lama Setelan baru
alamat delegateEmail
status verificationStatus

Perubahan lainnya:

  • Umum
    • Untuk menggunakan salah satu metode delegasi (termasuk delegates.create) pengguna delegator harus diaktifkan untuk Gmail. Artinya, misalnya, pengguna pendelegasi tidak dapat ditangguhkan di Google Workspace.
    • Alias email tidak dapat digunakan sebagai input email delegasi untuk metode baru. Pengguna delegasi harus dirujuk dengan alamat email primernya.
  • delegates.create
    • Metode ini kini dapat digunakan untuk membuat hubungan delegasi di beberapa domain yang termasuk dalam organisasi Google Workspaceyang sama.
    • Metode ini kini dapat digunakan untuk pengguna yang mewajibkan perubahan sandi saat login berikutnya.
    • Jika berhasil, metode ini akan menampilkan resource Users.settings.delegates dalam isi respons, bukan isi respons kosong.
    • Jika salah satu pengguna pendelegasi atau penerima delegasi dinonaktifkan (misalnya, ditangguhkan di Google Workspace), metode ini akan gagal dengan error HTTP 4XX, bukan error HTTP 500.
  • delegates.delete
    • Metode ini kini dapat digunakan untuk menghapus delegasi dengan verificationStatus apa pun, bukan hanya delegasi yang berupa accepted atau expired.
  • delegates.get
    • Ini adalah metode baru, yang mungkin lebih disukai daripada metode delegates.list, bergantung pada kebutuhan.

Mengelola setelan umum

Setelan umum tidak lagi tersedia melalui API.