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:

ForwardingAddress address = new ForwardingAddress()
        .setForwardingEmail("user2@example.com");
ForwardingAddress createAddressResult = gmailService.users().settings().forwardingAddresses()
        .create("me", address).execute();
if (createAddressResult.getVerificationStatus().equals("accepted")) {
    AutoForwarding autoForwarding = new AutoForwarding()
            .setEnabled(true)
            .setEmailAddress(address.getForwardingEmail())
            .setDisposition("trash");
    autoForwarding = gmailService.users().settings().updateAutoForwarding("me", autoForwarding).execute();

address = { 'forwardingEmail': 'user2@example.com' }
result = gmail_service.users().settings().forwardingAddresses().\
    create(userId='me', body=address).execute()
if result.get('verificationStatus') == 'accepted':
    body = {
        'emailAddress': result.get('forwardingEmail'),
        'enabled': True,
        'disposition': 'trash'
    }
    result = gmail_service.users().settings().\
        updateAutoForwarding(userId='me', body=body).execute()

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.