این سند تفاوتهای کلیدی بین Email Settings API و Gmail API را پوشش میدهد. میتوانید از این راهنما برای کمک به مهاجرت برنامه خود به Gmail API استفاده کنید.
تأیید درخواستها
مانند API تنظیمات ایمیل، API جیمیل از پروتکل OAuth 2.0 برای تأیید درخواستها استفاده میکند. یک تفاوت کلیدی این است که مجوزهای API جیمیل به یک کاربر خاص محدود میشوند، نه به کل دامنه. این بدان معناست که تأیید یک حساب کاربری مدیر دامنه به شما امکان انتقال ایمیل برای سایر کاربران در دامنه را نمیدهد. در عوض، شما باید از حسابهای کاربری استاندارد با مجوز در سطح دامنه که در کنسول مدیریت در لیست سفید قرار دارند، برای تولید توکن تأیید اعتبار مناسب استفاده کنید.
API تنظیمات ایمیل از این محدوده استفاده میکرد:
https://apps-apis.google.com/a/feeds/emailsettings/2.0/
محدودههای معادل در API جیمیل عبارتند از:
https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing
تغییرات پروتکل
API تنظیمات ایمیل از پروتکل GDATA مبتنی بر XML استفاده میکند. API جیمیل از 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>
رابط برنامهنویسی کاربردی جیمیل
POST https://www.googleapis.com/gmail/v1/users/{username}/labels
{
"name": "status updates"
}
به جای پیادهسازی مستقیم پروتکل، از کتابخانههای کلاینت ارائه شده استفاده کنید.
مدیریت برچسبها
برای مدیریت برچسبها در Gmail API، از منبع Labels استفاده کنید.
| محیط قدیمی | تنظیمات جدید | یادداشتها |
|---|---|---|
| شناسه برچسب | شناسه | |
| برچسب | نام | |
| خوانده نشدهتعداد | پیامهاخوانده نشده | |
| قابلیت مشاهده | قابلیت مشاهده لیست برچسب | SHOW اکنون labelShow استHIDE اکنون labelHide است |
سایر تغییرات:
- هنگام بهروزرسانی یا حذف برچسبها، رابط برنامهنویسی کاربردی (API) جیمیل به جای نام، برچسبها را با شناسه (ID) ارجاع میدهد.
مدیریت فیلترها
برای مدیریت فیلترها در Gmail API، از منبع Filters استفاده کنید.
| محیط قدیمی | تنظیمات جدید | یادداشتها |
|---|---|---|
| از | معیارها.از | |
| به | معیارها.to | |
| موضوع | معیارها.موضوع | |
| hasTheWord | معیارها.پرس و جو | |
| doesNotHaveTheWord | معیارهای.query نفی شده | |
| پیوست دارد | پیوست معیارها | |
| بایگانی باید | شناسههای اکشن.removeLabel | استفاده از INBOX به عنوان شناسه برچسب |
| shouldMarkAsRead | شناسههای اکشن.removeLabel | UNREAD به عنوان شناسه برچسب استفاده کنید |
| بایداستار | شناسههای اکشن.addLabelIds | STARRED به عنوان شناسه برچسب استفاده کنید |
| برچسب | شناسههای اکشن.addLabelIds | برای اضافه کردن از شناسه برچسب استفاده کنید |
| به جلو | اقدام.به جلو | |
| shouldTrash | شناسههای اکشن.addLabelIds | TRASH به عنوان شناسه برچسب استفاده کنید |
| هرگز هرزنامه | شناسههای اکشن.removeLabel | SPAM به عنوان شناسه برچسب استفاده کنید |
سایر تغییرات:
- اگر برچسب کاربری از قبل وجود ندارد، باید به طور صریح با استفاده از متد labels.create ایجاد شود.
مدیریت نامهای مستعار ارسالی
برای مدیریت نامهای مستعار ارسالی در Gmail API، از منبع SendAs استفاده کنید.
| محیط قدیمی | تنظیمات جدید |
|---|---|
| نام | نام نمایش |
| آدرس | ارسال به عنوان ایمیل |
| پاسخ به | پاسخ به آدرس |
| makeDefault | isDefault |
مدیریت کلیپهای وب
تنظیمات Web Clip دیگر از طریق API در دسترس نیستند.
مدیریت تنظیمات ارسال خودکار
برای مدیریت ارسال خودکار ایمیل در Gmail API، از منبع تنظیمات استفاده کنید.
| محیط قدیمی | تنظیمات جدید | یادداشتها |
|---|---|---|
| فعال کردن | فعال شده | |
| به جلو | آدرس ایمیل | |
| عمل | وضع | KEEP اکنون leaveInInbox استARCHIVE اکنون archive استDELETE اکنون trash استMARK_READ اکنون markRead است. |
سایر تغییرات:
- آدرسهای ارسال باید قبل از استفاده ایجاد و تأیید شوند
- آدرسهای ارسالی را میتوان از طریق منبع ForwardingAddresses مدیریت کرد.
مدیریت تنظیمات POP
برای مدیریت دسترسی POP در Gmail API، از منبع تنظیمات استفاده کنید.
| محیط قدیمی | تنظیمات جدید | یادداشتها |
|---|---|---|
| فعال کردن | پنجره دسترسی | وقتی روی disabled تنظیم شود، غیرفعال میشود |
| فعال کردن | پنجره دسترسی | ALL_MAIL حالا allMail استMAIL_FROM_NOW_ON حالا fromNowOn است. |
| عمل | وضع | KEEP اکنون leaveInInbox استARCHIVE اکنون archive استDELETE اکنون trash استMARK_READ اکنون markRead است. |
مدیریت تنظیمات IMAP
برای مدیریت دسترسی IMAP در Gmail API، از منبع تنظیمات استفاده کنید.
| محیط قدیمی | تنظیمات جدید |
|---|---|
| فعال کردن | فعال شده |
مدیریت تنظیمات پاسخ خودکار در تعطیلات
برای مدیریت پاسخ خودکار در تعطیلات در API جیمیل، از منبع تنظیمات استفاده کنید.
| محیط قدیمی | تنظیمات جدید |
|---|---|
| فقط مخاطبین | محدود کردن مخاطبین |
| فقط دامنه | restrictToDomain |
| فعال کردن | فعال کردن پاسخ خودکار |
| تاریخ پایان | پایان زمان |
| پیام | پاسخبدنه اچتیامال متن سادهی پاسخ |
| تاریخ شروع | زمان شروع |
| موضوع | موضوع پاسخ |
مدیریت تنظیمات امضا
برای مدیریت امضاهای ایمیل در Gmail API، از منبع SendAs استفاده کنید.
| محیط قدیمی | تنظیمات جدید |
|---|---|
| امضا | امضا |
سایر تغییرات:
- امضاها اکنون با نام مستعار مدیریت میشوند.
مدیریت تنظیمات زبان
برای مدیریت تنظیمات زبان در Gmail API، از منبع تنظیمات استفاده کنید.
| محیط قدیمی | تنظیمات جدید |
|---|---|
| زبان | زبان نمایش |
برای اطلاعات بیشتر، لطفاً به راهنمای مدیریت تنظیمات زبان مراجعه کنید.
مدیریت تنظیمات تفویض اختیار
برای مدیریت واگذاری اختیارات در Gmail API، از منبع Delegates استفاده کنید.
| محیط قدیمی | تنظیمات جدید |
|---|---|
| آدرس | نمایندهایمیل |
| وضعیت | وضعیت تأیید |
سایر تغییرات:
- عمومی
- برای استفاده از هر یک از متدهای واگذاری اختیار (از جمله delegates.create )، کاربر واگذارکننده باید برای Gmail فعال باشد. به عنوان مثال، به این معنی که کاربر واگذارکننده را نمیتوان در Google Workspace به حالت تعلیق درآورد.
- نمیتوان از نام مستعار ایمیل به عنوان ورودی ایمیل نماینده برای هیچ یک از متدهای جدید استفاده کرد. کاربر نماینده باید با آدرس ایمیل اصلی خود ارجاع داده شود.
- نمایندگان.ایجاد
- اکنون میتوان از این روش برای ایجاد روابط نماینده در چندین دامنه متعلق به یک سازمان Google Workspace استفاده کرد.
- این روش اکنون میتواند برای کاربرانی که نیاز به تغییر رمز عبور در ورود بعدی خود دارند، استفاده شود.
- در صورت موفقیت، این متد به جای یک بدنه پاسخ خالی، یک منبع Users.settings.delegates را در بدنه پاسخ برمیگرداند.
- اگر هر یک از کاربران delegator یا delegate غیرفعال باشند (مثلاً در Google Workspace به حالت تعلیق درآمده باشند)، این روش به جای خطای HTTP 500 با خطای HTTP 4XX مواجه میشود.
- نمایندگان.حذف
- اکنون میتوان از این روش برای حذف نمایندگانی با هر وضعیت تأییدی استفاده کرد، نه فقط نمایندگانی که
acceptedیاexpired.
- اکنون میتوان از این روش برای حذف نمایندگانی با هر وضعیت تأییدی استفاده کرد، نه فقط نمایندگانی که
- نمایندگان.دریافت
- این یک روش جدید است که بسته به نیاز، ممکن است نسبت به روش delegates.list ارجحیت داشته باشد.
مدیریت تنظیمات عمومی
تنظیمات عمومی دیگر از طریق API در دسترس نیستند.