מעבר מ-Email Settings API

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

אישור בקשות

בדומה ל-Email Settings API, גם Gmail API משתמש בפרוטוקול OAuth 2.0 כדי לאשר בקשות. הבדל מרכזי אחד הוא שההרשאות של Gmail API מוגבלות למשתמש ספציפי, ולא לכל הדומיין. כלומר, אישור של חשבון אדמין בדומיין לא מאפשר לכם להעביר את הדואר של משתמשים אחרים בדומיין. במקום זאת, צריך להשתמש בחשבונות שירות רגילים עם הרשאה בכל הדומיין שנוספו לרשימת ההיתרים במסוף Google 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

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

ב-Email Settings API נעשה שימוש בפרוטוקול GDATA שמבוסס על XML. ‫Gmail API משתמש ב-JSON. מכיוון שההגדרות מורכבות בעיקר מזוגות של מפתח-ערך, המבנה של מטען הייעודי דומה בין הגרסאות.

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

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, משתמשים במשאב settings.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, צריך להשתמש במשאב settings.sendAs.

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

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

ההגדרות של קליפים מהאינטרנט לא זמינות ב-Gmail API.

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

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

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

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

  • כדי להשתמש בכתובות להעברה, צריך ליצור אותן ולאמת אותן.
  • כדי לנהל כתובות להעברת אימייל, משתמשים במשאב settings.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, צריך להשתמש במשאב settings.sendAs.

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

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

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

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

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

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

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

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

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

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

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

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

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

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