Von der Email Settings API migrieren

In diesem Dokument werden die wichtigsten Unterschiede zwischen der Email Settings API und der Gmail API beschrieben. Mit diesem Leitfaden können Sie Ihre App zur Gmail API migrieren.

Anfragen autorisieren

Wie bei der Email Settings API wird bei der Gmail API das OAuth 2.0-Protokoll verwendet, 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. Wenn Sie ein Domain-Administratorkonto autorisieren, können Sie also keine E-Mails für andere Nutzer in der Domain migrieren. Stattdessen müssen Sie Standarddienstkonten mit domainweiter Autorisierung verwenden, die in der Admin-Konsole auf die Zulassungsliste gesetzt werden, um das entsprechende Authentifizierungstoken zu generieren.

Für die Email Settings API wurde der 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 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

Wenn Sie Labels in der Gmail API verwalten möchten, verwenden Sie die Ressource Labels.

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

Sonstige Änderungen:

  • Beim Aktualisieren oder Löschen von Labels verweist die Gmail API anhand der ID und nicht anhand des Namens auf Labels.

Filter verwalten

Wenn Sie Filter in der Gmail API verwalten möchten, verwenden Sie die Filter-Ressource.

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 hinzuzufügenden Labels verwenden
forwardTo action.forward
shouldTrash action.addLabelIds TRASH als Label-ID verwenden
neverSpam action.removeLabelIds SPAM als Label-ID verwenden

Sonstige Änderungen:

  • Wenn das hinzuzufügende Nutzerlabel noch nicht vorhanden ist, muss es explizit mit der Methode labels.create erstellt werden.

„Senden als“-Aliasse verwalten

Verwenden Sie die Ressource SendAs, um Send-as-Aliasse in der Gmail API zu verwalten.

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

Webclips verwalten

Web Clip-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
aktivieren aktiviert
forwardTo emailAddress
Aktion disposition KEEP heißt jetzt leaveInInbox
ARCHIVE heißt jetzt archive
DELETE heißt jetzt trash
MARK_READ heißt jetzt markRead

Sonstige Änderungen:

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

POP-Einstellungen verwalten

Verwenden Sie die Ressource Settings, 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 heißt jetzt leaveInInbox
ARCHIVE heißt jetzt archive
DELETE heißt jetzt trash
MARK_READ heißt jetzt markRead

IMAP-Einstellungen verwalten

Verwenden Sie die Ressource Settings, 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 Settings, um automatische Abwesenheitsnotizen 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

Wenn Sie E‑Mail-Signaturen in der Gmail API verwalten möchten, verwenden Sie die Ressource SendAs.

Alte Einstellung Neue Einstellung
Signatur Signatur

Sonstige Änderungen:

  • Signaturen werden jetzt pro Alias verwaltet.

Spracheinstellungen verwalten

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

Alte Einstellung Neue Einstellung
Sprache displayLanguage

Weitere Informationen finden Sie im Leitfaden zum Verwalten von Spracheinstellungen.

Delegierungseinstellungen verwalten

Verwenden Sie zum Verwalten der Delegierung in der Gmail API die Ressource Delegates.

Alte Einstellung Neue Einstellung
Adresse delegateEmail
Status verificationStatus

Sonstige Änderungen:

  • Allgemein
    • Damit eine der Delegierungsmethoden (einschließlich delegates.create) verwendet werden kann, muss Gmail für den delegierenden Nutzer aktiviert sein. Das bedeutet beispielsweise, dass der delegierende Nutzer innicht gesperrt werden kann.
    • Ein E‑Mail-Alias kann nicht als E‑Mail-Eingabe für den Bevollmächtigten für eine der neuen Methoden verwendet werden. Ein delegierter Nutzer muss mit seiner primären E-Mail-Adresse angegeben werden.
  • delegates.create
    • Mit dieser Methode können jetzt Delegierungsbeziehungen für mehrere Domains erstellt werden, die zur selben -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 und nicht einen leeren Antworttext zurück.
    • Wenn der delegierende oder der delegierte Nutzer deaktiviert ist (z. B. in gesperrt), schlägt diese Methode mit einem HTTP-4XX-Fehler anstelle eines HTTP-500-Fehlers fehl.
  • delegates.delete
    • Mit dieser Methode können jetzt Bevollmächtigte mit einem beliebigen 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 möglicherweise der Methode delegates.list vorzuziehen ist.

Allgemeine Einstellungen verwalten

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