מעבר מ-Email Settings API

במסמך הזה מפורטים ההבדלים העיקריים בין Email Settings API לבין Gmail API. המדריך הזה יעזור לכם להעביר את האפליקציה שלכם ל-Gmail API.

אישור בקשות

בדומה ל-Email Settings API, גם Gmail API משתמש בפרוטוקול OAuth 2.0 כדי לאשר בקשות. הבדל חשוב אחד הוא שההרשאות של Gmail API מוגבלות למשתמש ספציפי, ולא לכל הדומיין. כלומר, אישור של חשבון אדמין בדומיין לא מאפשר לכם להעביר את הדואר של משתמשים אחרים בדומיין. במקום זאת, צריך להשתמש בחשבונות שירות רגילים עם הרשאה לכל הדומיין שנמצאים ברשימת ההיתרים במסוף Admin כדי ליצור את אסימון האימות המתאים.

ממשק Email Settings API השתמש בהיקף ההרשאות:

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

ההיקפים המקבילים ב-Gmail API הם:

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

שינויים בפרוטוקול

ה-API של הגדרות האימייל משתמש בפרוטוקול GDATA שמבוסס על XML. ‫Gmail API משתמש ב-JSON. מכיוון שההגדרות מורכבות בעיקר מצמדי מפתח/ערך, המטען הייעודי (payload) דומה בין הגרסאות מבחינה רעיונית.

דוגמה ליצירת תווית:

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>

ממשק ה-API של Gmail

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

במקום להטמיע את הפרוטוקול ישירות, צריך להשתמש בספריות הלקוח שסופקו.

ניהול תוויות

כדי לנהל תוויות ב-Gmail API, צריך להשתמש במשאב Labels.

ההגדרה הקודמת הגדרה חדשה הערות
labelId id [מזהה]
תווית שם
unreadCount messagesUnread
חשיפה labelListVisibility ‫SHOW נקרא עכשיו labelShow
HIDE נקרא עכשיו labelHide

שינויים אחרים:

  • כשמעדכנים או מוחקים תוויות, Gmail API מפנה לתוויות לפי מזהה ולא לפי שם.

ניהול המסננים

כדי לנהל מסננים ב-Gmail API, משתמשים במשאב Filters.

ההגדרה הקודמת הגדרה חדשה הערות
החל מ- criteria.from
עד criteria.to
נושא criteria.subject
hasTheWord criteria.query
doesNotHaveTheWord criteria.negatedQuery
hasAttachment criteria.hasAttachment
shouldArchive action.removeLabelIds שימוש ב-INBOX כמזהה התווית
shouldMarkAsRead action.removeLabelIds שימוש ב-UNREAD כמזהה התווית
shouldStar action.addLabelIds שימוש ב-STARRED כמזהה התווית
תווית action.addLabelIds שימוש במזהה של התווית להוספה
forwardTo action.forward
shouldTrash action.addLabelIds שימוש ב-TRASH כמזהה התווית
neverSpam action.removeLabelIds שימוש ב-SPAM כמזהה התווית

שינויים אחרים:

  • אם התווית שרוצים להוסיף למשתמש עדיין לא קיימת, צריך ליצור אותה במפורש באמצעות השיטה labels.create.

ניהול כינויים לשליחה בתור

כדי לנהל כתובות אימייל חלופיות לשליחה ב-Gmail API, צריך להשתמש במשאב SendAs.

ההגדרה הקודמת הגדרה חדשה
שם displayName
כתובת sendAsEmail
replyTo replyToAddress
makeDefault isDefault

ניהול קליפים מהאינטרנט

ההגדרות של Web Clip כבר לא זמינות דרך ה-API.

ניהול ההגדרות של העברה אוטומטית

כדי לנהל את ההעברה האוטומטית ב-Gmail API, משתמשים במשאב Settings.

ההגדרה הקודמת הגדרה חדשה הערות
enable פעיל
forwardTo emailAddress
פעולה מחיקה ‫KEEP נקרא עכשיו leaveInInbox
ARCHIVE נקרא עכשיו archive
DELETE נקרא עכשיו trash
MARK_READ נקרא עכשיו markRead

שינויים אחרים:

  • צריך ליצור ולאמת את הכתובות להעברה לפני שמשתמשים בהן
  • אפשר לנהל כתובות להעברה באמצעות מקור המידע ForwardingAddresses.

ניהול הגדרות POP

כדי לנהל את הגישה ל-POP ב-Gmail API, משתמשים במשאב Settings.

ההגדרה הקודמת הגדרה חדשה הערות
enable accessWindow האפשרות מושבתת כשהערך הוא disabled
enableFor accessWindow ‫ALL_MAIL נקרא עכשיו allMail
MAIL_FROM_NOW_ON נקרא עכשיו fromNowOn
פעולה מחיקה ‫KEEP נקרא עכשיו leaveInInbox
ARCHIVE נקרא עכשיו archive
DELETE נקרא עכשיו trash
MARK_READ נקרא עכשיו markRead

ניהול הגדרות IMAP

כדי לנהל את הגישה ל-IMAP ב-Gmail API, משתמשים במשאב Settings.

ההגדרה הקודמת הגדרה חדשה
enable פעיל

ניהול ההגדרות של מענה אוטומטי בחופשה

כדי לנהל את המענה האוטומטי לחופשה ב-Gmail API, משתמשים במשאב Settings.

ההגדרה הקודמת הגדרה חדשה
contactsOnly restrictToContacts
domainOnly restrictToDomain
enable enableAutoReply
endDate endTime
הודעה responseBodyHtml
responseBodyPlainText
startDate startTime
נושא responseSubject

ניהול הגדרות החתימה

כדי לנהל חתימות אימייל ב-Gmail API, צריך להשתמש במשאב SendAs.

ההגדרה הקודמת הגדרה חדשה
signature signature

שינויים אחרים:

  • חתימות מנוהלות עכשיו לכל כתובת אימייל חלופית.

ניהול הגדרות השפה

כדי לנהל את הגדרות השפה ב-Gmail API, משתמשים במשאב Settings.

ההגדרה הקודמת הגדרה חדשה
language displayLanguage

מידע נוסף זמין במדריך לניהול הגדרות השפה.

ניהול הגדרות ההאצלה

כדי לנהל הקצאת הרשאות ב-Gmail API, צריך להשתמש במשאב Delegates.

ההגדרה הקודמת הגדרה חדשה
כתובת delegateEmail
status verificationStatus

שינויים אחרים:

  • כללי
    • כדי להשתמש באחת משיטות ההענקה (כולל delegates.create), צריך להפעיל את Gmail למשתמש שמעניק את הגישה. לדוגמה, אי אפשר להשעות את המשתמש שהעניק את ההרשאה ב-Google Workspace.
    • אי אפשר להשתמש בכתובת אימייל חלופית כקלט של כתובת האימייל של הנציג באף אחת מהשיטות החדשות. צריך להפנות למשתמש עם הרשאת גישה באמצעות כתובת האימייל הראשית שלו.
  • delegates.create
    • מעכשיו אפשר להשתמש בשיטה הזו כדי ליצור יחסי גומלין של הקצאת הרשאות בכמה דומיינים ששייכים לאותו ארגון Google Workspace.
    • עכשיו אפשר להשתמש בשיטה הזו גם עבור משתמשים שנדרשים לשנות את הסיסמה שלהם בכניסה הבאה.
    • אם הפעולה בוצעה ללא שגיאות, השיטה הזו מחזירה משאב Users.settings.delegates בגוף התגובה, ולא גוף תגובה ריק.
    • אם אחד מהמשתמשים (המשתמש שהוקצו לו הרשאות או המשתמש שהקצה הרשאות) מושבת (לדוגמה, מושעה ב- Google Workspace), השיטה הזו תיכשל עם שגיאת HTTP 4XX במקום שגיאת HTTP 500.
  • delegates.delete
    • עכשיו אפשר להשתמש בשיטה הזו כדי למחוק נציגים עם כל verificationStatus, ולא רק נציגים עם הערכים accepted או expired.
  • delegates.get
    • זו שיטה חדשה, ויכול להיות שהיא עדיפה על השיטה delegates.list, בהתאם לצורך.

ניהול הגדרות כלליות

ההגדרות הכלליות לא זמינות יותר דרך ה-API.