Von der Email Settings API migrieren

In diesem Dokument werden die wichtigsten Unterschiede zwischen der Email Settings API und der Gmail API beschrieben. Dieser Leitfaden kann Ihnen dabei helfen, Ihre Anwendung zur Gmail API zu migrieren.

Anfragen autorisieren

Wie die Email Settings API verwendet auch die Gmail API das OAuth 2.0-Protokoll, um Anfragen zu autorisieren. Ein wichtiger Unterschied besteht darin, dass Gmail API-Berechtigungen auf einen einzelnen Nutzer und nicht auf die gesamte Domain beschränkt sind. Das bedeutet, dass Sie durch die Autorisierung eines Domainadministratorkontos keine E-Mails für andere Nutzer in der Domain migrieren können. Stattdessen müssen Sie Standarddienstkonten mit domainweiter Befugnis verwenden, die in der Admin-Konsole auf die Zulassungsliste gesetzt werden, um das entsprechende Authentifizierungstoken zu generieren.

Die Email Settings API hat den Bereich verwendet:

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

Die entsprechenden Bereiche in der Gmail API sind:

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

Protokolländerungen

Die Email Settings API verwendet das XML-basierte GDATA-Protokoll. Die Gmail API verwendet JSON. Da Einstellungen hauptsächlich aus Schlüssel/Wert-Paaren bestehen, sind die Nutzlasten zwischen Versionen konzeptionell ähnlich.

Beispiel für das Erstellen eines Labels:

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"
}

Verwenden Sie die bereitgestellten Clientbibliotheken, anstatt das Protokoll direkt zu implementieren.

Labels verwalten

Verwenden Sie zum Verwalten von Labels in der Gmail API die Ressource Labels.

Alte Einstellung Neue Einstellung Hinweise
labelId id
Label name
unreadCount messagesUnread
Sichtbarkeit labelListVisibility SHOW ist jetzt labelShow
HIDE ist jetzt labelHide

Weitere Änderungen:

  • Beim Aktualisieren oder Löschen von Labels verweist die Gmail API auf Labels nach ID und nicht nach Namen.

Filter verwalten

Verwenden Sie zum Verwalten von Filtern in der Gmail API die Ressource Filter.

Alte Einstellung Neue Einstellung Hinweise
von criteria.from
zu criteria.to
Betreff criteria.subject
hasTheWord criteria.query
doesNotHaveTheWord criteria.negatedQuery
hasAttachment criteria.hasAttachment
shouldArchive action.removeLabelIds INBOX als Label-ID verwenden
shouldMarkAsRead action.removeLabelIds UNREAD als Label-ID verwenden
shouldStar action.addLabelIds STARRED als Label-ID verwenden
Label action.addLabelIds ID des Labels verwenden, das hinzugefügt werden soll
forwardTo action.forward
shouldTrash action.addLabelIds TRASH als Label-ID verwenden
neverSpam action.removeLabelIds SPAM als Label-ID verwenden

Weitere Änderungen:

  • Wenn das Hinzufügen eines Nutzerlabels noch nicht vorhanden ist, muss es explizit mit der Methode labels.create erstellt werden.

„Senden als“-Aliasse verwalten

Verwenden Sie die Ressource SendAs, um „Senden als“-Aliasse in der Gmail API zu verwalten.

Alte Einstellung Neue Einstellung
name displayName
Adresse sendAsEmail
replyTo replyToAddress
makeDefault isDefault

Web-Clips verwalten

Webclip-Einstellungen sind nicht mehr über die API verfügbar.

Einstellungen für die automatische Weiterleitung verwalten

Verwenden Sie die Ressource Settings, um die automatische Weiterleitung in der Gmail API zu verwalten.

Alte Einstellung Neue Einstellung Hinweise
enable aktiviert
forwardTo emailAddress
Aktion disposition KEEP ist jetzt leaveInInbox
ARCHIVE ist jetzt archive
DELETE ist jetzt trash
MARK_READ ist jetzt markRead

Weitere Änderungen:

  • Weiterleitungsadressen müssen vor der Verwendung erstellt und bestätigt werden
  • Weiterleitungsadressen können über die Ressource ForwardingAddresses verwaltet werden.

POP-Einstellungen verwalten

Den POP-Zugriff in der Gmail API verwalten Sie über die Ressource Einstellungen.

Alte Einstellung Neue Einstellung Hinweise
enable accessWindow Deaktiviert, wenn auf „disabled“ festgelegt
enableFor accessWindow ALL_MAIL ist jetzt allMail
MAIL_FROM_NOW_ON ist jetzt fromNowOn
Aktion disposition KEEP ist jetzt leaveInInbox
ARCHIVE ist jetzt archive
DELETE ist jetzt trash
MARK_READ ist jetzt markRead

IMAP-Einstellungen verwalten

Zum Verwalten des IMAP-Zugriffs in der Gmail API verwenden Sie die Ressource Settings (Einstellungen).

Alte Einstellung Neue Einstellung
enable aktiviert

Einstellungen für automatische Abwesenheitsnotizen verwalten

Verwenden Sie zum Verwalten der automatischen Abwesenheitsnotiz in der Gmail API die Ressource Einstellungen.

Alte Einstellung Neue Einstellung
contactsOnly restrictToContacts
domainOnly restrictToDomain
enable enableAutoReply
endDate endTime
Nachricht AntwortBodyHTML
responseBodyPlainText
startDate startTime
Betreff responseSubject

Signatureinstellungen verwalten

Verwenden Sie die Ressource SendAs, um E-Mail-Signaturen in der Gmail API zu verwalten.

Alte Einstellung Neue Einstellung
Signatur Signatur

Weitere Änderungen:

  • Signaturen werden jetzt pro Alias verwaltet.

Spracheinstellungen verwalten

Die Spracheinstellungen in der Gmail API können über die Ressource Einstellungen verwaltet werden.

Alte Einstellung Neue Einstellung
language displayLanguage

Weitere Informationen finden Sie im Leitfaden zum Verwalten von Spracheinstellungen.

Delegierungseinstellungen verwalten

Mit der Ressource Delegates können Sie die Delegierung in der Gmail API verwalten.

Alte Einstellung Neue Einstellung
Adresse delegateEmail
status verificationStatus

Weitere Änderungen:

  • Allgemein
    • Damit Sie Delegierungsmethoden wie delegates.create verwenden können, muss der Nutzer, der die Bevollmächtigung hat, für Gmail aktiviert sein. Das bedeutet, dass der Bevollmächtigende beispielsweise nicht inGoogle Workspacegesperrt werden kann.
    • Ein E-Mail-Alias kann nicht als delegierte E-Mail-Eingabe für die neuen Methoden verwendet werden. Ein Bevollmächtigter muss über seine primäre E-Mail-Adresse an ihn verwiesen werden.
  • delegates.create
    • Diese Methode kann jetzt verwendet werden, um delegierte Beziehungen über mehrere Domains hinweg zu erstellen, die zur selben Google Workspace-Organisation gehören.
    • Diese Methode kann jetzt für Nutzer verwendet werden, die bei ihrer nächsten Anmeldung eine Passwortänderung erforderlich machen.
    • Wenn der Vorgang erfolgreich ist, wird mit dieser Methode eine Ressource vom Typ "Users.settings.delegates" im Antworttext anstatt eines leeren Antworttexts zurückgegeben.
    • Wenn einer der delegierenden oder delegierten Nutzer deaktiviert ist (z. B. in Google Workspacegesperrt), schlägt diese Methode mit einem HTTP 4XX-Fehler anstelle eines HTTP 500-Fehlers fehl.
  • delegates.delete
    • Mit dieser Methode können Sie jetzt Bevollmächtigte mit einem beliebigen verificationStatus löschen und nicht nur Bevollmächtigte mit dem Status accepted oder expired.
  • delegates.get
    • Dies ist eine neue Methode, die je nach Bedarf gegenüber der Methode delegates.list vorgezogen werden kann.

Allgemeine Einstellungen verwalten

Allgemeine Einstellungen sind nicht mehr über die API verfügbar.