Migrate from the App Engine Mail API to an SMTP-based service

To improve email security and ensure reliable, high-volume email delivery, migrate from the legacy Mail API to a standard third-party email provider service that uses the Simple Mail Transfer Protocol (SMTP), such as SendGrid, Mailgun, or Mailjet.

This guide describes the process for migrating outbound email services from the Mail API to an SMTP-based email service. You can apply these instructions to migrate to any SMTP-based third-party email provider, or use another supported runtime. This guide doesn't provide steps for migrating inbound messaging that uses a third-party alternative.

The SMTP standard offers the following benefits over the legacy App Engine Mail API:

SMTP-based services provide improved email delivery by reducing the likelihood of emails being marked as spam.
With SMTP-based services, you can access detailed analytics reports on email opens, clicks, and bounces. These reports provide useful information about how users interact with your emails.
You have complete control over your sender reputation and email authentication.
Increased daily send limits compared to the legacy Mail API with access to advanced features like A/B testing, segmentation, and templating.

Overview of the migration process

The migration process includes the following steps:

Set up the SMTP-based email service to get your SMTP credentials.
Verify your sender identity to authenticate with your domain or email address.
Configure your source files with your SMTP credentials and sending method, and then deploy your application.
Test your application to check your email functionality.

Set up the SMTP-based email service

Set up an account with a standard third-party email provider that uses SMTP, such as SendGrid, Mailgun, or Mailjet and retrieve the following information from your chosen provider:

SMTP Host: The SMTP server address used for sending mail. For example, smtp.sendgrid.net or example.mailjet.com.
Port: The port number for the connection. For example 587 for TLS encryption.
Username: Your account's SMTP login username.
Password or API Key: Your account's password or an API key, which acts as the password for the SMTP connection. For some providers like SendGrid, the username is a fixed value like apikey, and the API key is used as the password.

Verify your sender identity

To prevent spam, all email services require you to verify that you are the owner of the email address or domain you are sending emails from. This step often involves adding specific DNS details, such as CNAME records to your domain host's DNS management page.

Follow your provider's instructions to verify your sender identity before proceeding with the application configuration.

To add DNS records to your domain host, follow these steps:

Sign in to your DNS provider service.
Navigate to the DNS management page for your domain.
Add the CNAME records exactly as provided by your email service provider. For each record, do the following:
- In the Name or Host field, enter the host details.
- In the Points or Value field, enter the value.

DNS changes might take a few hours to become active. If your verification fails, wait for some time, and try again.

Configure your source files

To include the SMTP functionality, follow these steps:

Run the following command to install Maven:
```
sudo apt install maven 
```

Add the following code in your pom.xml file to switch to the SMTP service:

Add the version for the appengine-api-1.0-sdk dependency:

 <dependency>  <groupId>com.google.appengine</groupId>  <artifactId>appengine-api-1.0-sdk</artifactId>  <version>2.0.38</version>  </dependency>

Update your project ID:

 <configuration>  <deploy.projectId>PROJECT-ID</deploy.projectId>  <deploy.version>1</deploy.version>  </configuration>

Replace PROJECT-ID with your Google Cloud project ID.

Add the following environment variables in your appengine-web.xml file to include your SMTP sender configurations:

... <runtime>RUNTIME</runtime> <service>default</service> <threadsafe>true</threadsafe> <app-engine-apis>true</app-engine-apis> <env-variables> <!-- This is the master switch to enable the SMTP service.--> <env-var name="APPENGINE_USE_SMTP_MAIL_SERVICE" value="true" /> <!-- SMTP Server Configuration --> <!-- The server address from your mail provider.--> <env-var name="APPENGINE_SMTP_HOST" value="SMTP_HOST" /> <!-- The recommended port for TLS connections. --> <env-var name="APPENGINE_SMTP_PORT" value="587" /> <!-- The username for your SMTP login. --> <env-var name="APPENGINE_SMTP_USER" value="SMTP_USER" /> <!-- The API key or password --> <env-var name="APPENGINE_SMTP_PASSWORD" value="SMTP_PASSWORD" /> <!-- Use TLS for a secure connection. --> <env-var name="APPENGINE_SMTP_USE_TLS" value="true" /> </env-variables> ... </appengine-web-app>

Replace the following:

RUNTIME: a supported Java runtime version.
SMTP_HOST: the SMTP host address. For example, smtp.sendgrid.net or example.mailjet.com.
SMTP_USER: your account's SMTP login username. For example, apiKey.
SMTP_PASSWORD: the password or API key you obtained from your third-party email provider. For improved security, we recommend that you use the Secret Manager to store your API key instead of placing it in the appengine-web.xml file.

Run the following command to deploy your application:
```
mvn package appengine:deploy 
```

Test your application

Migration is successful if you are able to deploy your app without errors. To verify that your mail service is working, follow these steps:

Trigger the part of your application that sends an email.
Check the Logs Explorer to make sure there are no errors related to the API calls or the SMTP connection attempt.
Sign in to your third-party email provider's account (e.g., Mailgun, Mailjet, SendGrid) and check their Activity Feed, Logs, or Delivery Dashboard. Your test email should appear in the feed with a delivery status marked as Processed, Delivered, or similar.