Von der Email Settings API migrieren

In diesem Dokument werden die wichtigsten Unterschiede zwischen der Email Settings API und der Gmail API beschrieben. In diesem Leitfaden erfahren Sie, wie Sie Ihre App zur Gmail API 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 die Berechtigungen der Gmail API auf einen einzelnen Nutzer und nicht auf die gesamte Domain angewendet werden. Das bedeutet, dass Sie mit der Autorisierung eines Domainadministratorkontos keine E-Mails für andere Nutzer in der Domain migrieren können. Stattdessen müssen Sie Standarddienstkonten mit domainweiter Autorisierung verwenden, die in der Admin-Konsole auf die Zulassungsliste gesetzt sind, um das entsprechende Authentifizierungstoken zu generieren.

Für die Email Settings API wurde der folgende 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 E-Mail-Einstellungen API verwendet das XML-basierte GDATA-Protokoll. Die Gmail API verwendet JSON. Da Einstellungen hauptsächlich aus Schlüssel/Wert-Paaren bestehen, sind Payloads zwischen den 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 die Ressource Labels, um Labels in der Gmail API zu verwalten.

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

Weitere Änderungen:

  • Wenn Labels in der Gmail API aktualisiert oder gelöscht werden, wird nicht auf den Namen, sondern auf die ID verwiesen.

Filter verwalten

Verwenden Sie die Ressource Filter, um Filter in der Gmail API zu verwalten.

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 Verwenden Sie INBOX als Label-ID.
shouldMarkAsRead action.removeLabelIds Verwenden Sie UNREAD als Label-ID.
shouldStar action.addLabelIds Verwenden Sie STARRED als Label-ID.
Label action.addLabelIds ID des Labels verwenden, das hinzugefügt werden soll
forwardTo action.forward
shouldTrash action.addLabelIds Verwenden Sie TRASH als Label-ID.
neverSpam action.removeLabelIds Verwenden Sie SPAM als Label-ID.

Weitere Änderungen:

  • Wenn Sie ein Nutzerlabel hinzufügen, das noch nicht vorhanden ist, muss es mit der Methode labels.create explizit erstellt werden.

Aliasse für das Senden als… verwalten

Verwenden Sie die Ressource SendAs, um Aliasse für das Senden als in der Gmail API zu verwalten.

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

Webclips verwalten

Einstellungen für Webclips sind nicht mehr über die API verfügbar.

Einstellungen für die automatische Weiterleitung verwalten

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

Alte Einstellung Neue Einstellung Hinweise
aktivieren 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

Verwenden Sie die Ressource Einstellungen, um den POP-Zugriff in der Gmail API zu verwalten.

Alte Einstellung Neue Einstellung Hinweise
aktivieren accessWindow Deaktiviert, wenn disabled festgelegt ist
enableFor accessWindow ALL_MAIL heißt jetzt allMail
MAIL_FROM_NOW_ON heißt jetzt fromNowOn
Aktion disposition KEEP ist jetzt leaveInInbox
ARCHIVE ist jetzt archive
DELETE ist jetzt trash
MARK_READ ist jetzt markRead

IMAP-Einstellungen verwalten

Verwenden Sie die Ressource Einstellungen, um den IMAP-Zugriff in der Gmail API zu verwalten.

Alte Einstellung Neue Einstellung
aktivieren aktiviert

Einstellungen für automatische Abwesenheitsnotizen verwalten

Verwenden Sie die Ressource Einstellungen, um die automatische Abwesenheitsnotiz in der Gmail API zu verwalten.

Alte Einstellung Neue Einstellung
contactsOnly restrictToContacts
domainOnly restrictToDomain
aktivieren enableAutoReply
endDate endTime
Nachricht responseBodyHtml
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

Verwenden Sie die Ressource Einstellungen, um die Spracheinstellungen in der Gmail API zu verwalten.

Alte Einstellung Neue Einstellung
Sprache displayLanguage

Weitere Informationen finden Sie im Leitfaden zum Verwalten der Spracheinstellungen.

Einstellungen für die Delegierung verwalten

Verwenden Sie die Ressource Delegates, um die Delegierung in der Gmail API zu verwalten.

Alte Einstellung Neue Einstellung
Adresse delegateEmail
Status verificationStatus

Weitere Änderungen:

  • Allgemein
    • Damit Sie eine der Delegierungsmethoden verwenden können (einschließlich delegates.create), muss der delegierende Nutzer für Gmail aktiviert sein. Das bedeutet beispielsweise, dass der delegierende Nutzer inGoogle Workspacenicht gesperrt werden kann.
    • Ein E-Mail-Alias kann nicht als E-Mail-Adresse des Bevollmächtigten für die neuen Methoden verwendet werden. Ein delegierter Nutzer muss über seine primäre E-Mail-Adresse verwiesen werden.
  • delegates.create
    • Mit dieser Methode können jetzt delegierte Beziehungen über mehrere Domains hinweg erstellt werden, die zu derselben Google Workspace-Organisation gehören.
    • Diese Methode kann jetzt für Nutzer verwendet werden, die bei der nächsten Anmeldung ihr Passwort ändern müssen.
    • Bei Erfolg gibt diese Methode eine Users.settings.delegates-Ressource im Antworttext zurück, keinen leeren Antworttext.
    • Wenn einer der delegierenden oder delegierten Nutzer deaktiviert ist (z. B. in Google Workspacegesperrt), schlägt diese Methode mit einem HTTP-4XX-Fehler statt einem HTTP-500-Fehler fehl.
  • delegates.delete
    • Mit dieser Methode können jetzt Bevollmächtigte mit beliebigem verificationStatus gelöscht werden, nicht nur Bevollmächtigte mit dem Status accepted oder expired.
  • delegates.get
    • Dies ist eine neue Methode, die je nach Bedarf der Methode delegates.list vorgezogen werden kann.

Allgemeine Einstellungen verwalten

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