Managing Forwarding

You can use Settings to configure forwarding for an account. To be used as a forwarding email address, an address must fulfill one of the following criteria:

The email address has been verified. For further information, see Creating and verifying forwarding addresses
The email address belongs to the same domain as the sender.
The email address belongs to a subdomain within the same domain of the sender.
The email address belongs to a domain alias configured as part of the same Google Workspace account.

If the forwarding email address doesn't adhere to one of these rules, setting up forwarding using the API fails.

For information on how to create , list , get , or delete forwarding addresses, see the ForwardingAddresses reference .

For information on how to get or update forwarding settings, see the Settings reference

Creating and verifying forwarding addresses

You must create forwarding addresses prior to use. In some cases, users must also verify ownership of the address as well.

If Gmail requires user verification for a forwarding address, the address is returned with the status pending . A verification message is automatically sent to the target email address. The owner of the email address must complete the verification process before it can be used.

Forwarding addresses that do not require verification have a verification status of accepted .

Enabling auto-forwarding

Call the updateAutoForwarding method to enable auto-forwarding for an account. The call requires both a registered and verified forwarding address as well as an action to take on forwarded messages.

For example, to enable auto-forwarding and move forwarded messages to the trash:

Java

gmail/snippets/src/main/java/EnableForwarding.java

View on GitHub

 import 
  
 com.google.api.client.googleapis.json.GoogleJsonError 
 ; 
 import 
  
 com.google.api.client.googleapis.json.GoogleJsonResponseException 
 ; 
 import 
  
 com.google.api.client.http.HttpRequestInitializer 
 ; 
 import 
  
 com.google.api.client.http.javanet.NetHttpTransport 
 ; 
 import 
  
 com.google.api.client.json.gson.GsonFactory 
 ; 
 import 
  
 com.google.api.services.gmail.Gmail 
 ; 
 import 
  
 com.google.api.services.gmail.GmailScopes 
 ; 
 import 
  
 com.google.api.services.gmail.model.AutoForwarding 
 ; 
 import 
  
 com.google.api.services.gmail.model.ForwardingAddress 
 ; 
 import 
  
 com.google.auth.http.HttpCredentialsAdapter 
 ; 
 import 
  
 com.google.auth.oauth2.GoogleCredentials 
 ; 
 import 
  
 java.io.IOException 
 ; 
 /* Class to demonstrate the use of Gmail Enable Forwarding API */ 
 public 
  
 class 
 EnableForwarding 
  
 { 
  
 /** 
 * Enable the auto-forwarding for an account. 
 * 
 * @param forwardingEmail - Email address of the recipient whose email will be forwarded. 
 * @return forwarding id and metadata, {@code null} otherwise. 
 * @throws IOException - if service account credentials file not found. 
 */ 
  
 public 
  
 static 
  
 AutoForwarding 
  
 enableAutoForwarding 
 ( 
 String 
  
 forwardingEmail 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 /* Load pre-authorized user credentials from the environment. 
 TODO(developer) - See https://developers.google.com/identity for 
 guides on implementing OAuth2 for your application. */ 
  
 GoogleCredentials 
  
 credentials 
  
 = 
  
 GoogleCredentials 
 . 
 getApplicationDefault 
 () 
  
 . 
 createScoped 
 ( 
 GmailScopes 
 . 
 GMAIL_SETTINGS_SHARING 
 ); 
  
 HttpRequestInitializer 
  
 requestInitializer 
  
 = 
  
 new 
  
 HttpCredentialsAdapter 
 ( 
 credentials 
 ); 
  
 // Create the gmail API client 
  
 Gmail 
  
 service 
  
 = 
  
 new 
  
 Gmail 
 . 
 Builder 
 ( 
 new 
  
 NetHttpTransport 
 (), 
  
 GsonFactory 
 . 
 getDefaultInstance 
 (), 
  
 requestInitializer 
 ) 
  
 . 
 setApplicationName 
 ( 
 "Gmail samples" 
 ) 
  
 . 
 build 
 (); 
  
 try 
  
 { 
  
 // Enable auto-forwarding and move forwarded messages to the trash 
  
 ForwardingAddress 
  
 address 
  
 = 
  
 new 
  
 ForwardingAddress 
 () 
  
 . 
 setForwardingEmail 
 ( 
 forwardingEmail 
 ); 
  
 ForwardingAddress 
  
 createAddressResult 
  
 = 
  
 service 
 . 
 users 
 (). 
 settings 
 (). 
 forwardingAddresses 
 () 
  
 . 
 create 
 ( 
 "me" 
 , 
  
 address 
 ). 
 execute 
 (); 
  
 if 
  
 ( 
 createAddressResult 
 . 
 getVerificationStatus 
 (). 
 equals 
 ( 
 "accepted" 
 )) 
  
 { 
  
 AutoForwarding 
  
 autoForwarding 
  
 = 
  
 new 
  
 AutoForwarding 
 () 
  
 . 
 setEnabled 
 ( 
 true 
 ) 
  
 . 
 setEmailAddress 
 ( 
 address 
 . 
 getForwardingEmail 
 ()) 
  
 . 
 setDisposition 
 ( 
 "trash" 
 ); 
  
 autoForwarding 
  
 = 
  
 service 
 . 
 users 
 (). 
 settings 
 (). 
 updateAutoForwarding 
 ( 
 "me" 
 , 
  
 autoForwarding 
 ). 
 execute 
 (); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 autoForwarding 
 . 
 toPrettyString 
 ()); 
  
 return 
  
 autoForwarding 
 ; 
  
 } 
  
 } 
  
 catch 
  
 ( 
 GoogleJsonResponseException 
  
 e 
 ) 
  
 { 
  
 // TODO(developer) - handle error appropriately 
  
 GoogleJsonError 
  
 error 
  
 = 
  
 e 
 . 
 getDetails 
 (); 
  
 if 
  
 ( 
 error 
 . 
 getCode 
 () 
  
 == 
  
 403 
 ) 
  
 { 
  
 System 
 . 
 err 
 . 
 println 
 ( 
 "Unable to enable forwarding: " 
  
 + 
  
 e 
 . 
 getDetails 
 ()); 
  
 } 
  
 else 
  
 { 
  
 throw 
  
 e 
 ; 
  
 } 
  
 } 
  
 return 
  
 null 
 ; 
  
 } 
 }

Python

gmail/snippet/settings snippets/enable_forwarding.py

View on GitHub

 import 
  
 google.auth 
 from 
  
 googleapiclient.discovery 
  
 import 
 build 
 from 
  
 googleapiclient.errors 
  
 import 
 HttpError 
 def 
  
 enable_forwarding 
 (): 
  
 """Enable email forwarding. 
 Returns:Draft object, including forwarding id and result meta data. 
 Load pre-authorized user credentials from the environment. 
 TODO(developer) - See https://developers.google.com/identity 
 for guides on implementing OAuth2 for the application. 
 """ 
 creds 
 , 
 _ 
 = 
 google 
 . 
 auth 
 . 
 default 
 () 
 try 
 : 
 # create gmail api client 
 service 
 = 
 build 
 ( 
 "gmail" 
 , 
 "v1" 
 , 
 credentials 
 = 
 creds 
 ) 
 address 
 = 
 { 
 "forwardingEmail" 
 : 
 "gduser1@workspacesamples.dev" 
 } 
 # pylint: disable=E1101 
 result 
 = 
 ( 
 service 
 . 
 users 
 () 
 . 
 settings 
 () 
 . 
 forwardingAddresses 
 () 
 . 
 create 
 ( 
 userId 
 = 
 "me" 
 , 
 body 
 = 
 address 
 ) 
 . 
 execute 
 () 
 ) 
 if 
 result 
 . 
 get 
 ( 
 "verificationStatus" 
 ) 
 == 
 "accepted" 
 : 
 body 
 = 
 { 
 "emailAddress" 
 : 
 result 
 . 
 get 
 ( 
 "forwardingEmail" 
 ), 
 "enabled" 
 : 
 True 
 , 
 "disposition" 
 : 
 "trash" 
 , 
 } 
 # pylint: disable=E1101 
 result 
 = 
 ( 
 service 
 . 
 users 
 () 
 . 
 settings 
 () 
 . 
 updateAutoForwarding 
 ( 
 userId 
 = 
 "me" 
 , 
 body 
 = 
 body 
 ) 
 . 
 execute 
 () 
 ) 
 print 
 ( 
 f 
 "Forwarding is enabled : 
 { 
 result 
 } 
 " 
 ) 
 except 
 HttpError 
 as 
 error 
 : 
 print 
 ( 
 f 
 "An error occurred: 
 { 
 error 
 } 
 " 
 ) 
 result 
 = 
 None 
 return 
 result 
 if 
 __name__ 
 == 
 "__main__" 
 : 
 enable_forwarding 
 ()

To disable autoforwarding, call updateAutoForwarding and set the enabled property to false .

Forwarding specific messages

Auto-forwarding sends all received messages to the target account. To selectively forward messages, use filters to create rules that forward in response to message attributes or content.

Managing Forwarding Stay organized with collections Save and categorize content based on your preferences.