Managing Forwarding

You can use Settings to configure forwarding for an account. Messages can only be forwarded to registered and verified email addresses.

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.