This tutorial shows how to use SendGrid to send email from an app running on a Compute Engine instance. SendGrid is a third-party email service that offers Compute Engine users a free trial with 12,000 transactional emails free each month.
Objectives
- Use SendGrid with Postfix on a Compute Engine instance.
- Use SendGrid in Java code running on a Compute Engine instance.
- Use SendGrid in Node.js code running on a Compute Engine instance.
Costs
This tutorial uses billable components of Google Cloud including Compute Engine.
New Google Cloud users might be eligible for a free trial.Before you begin
-
Sign in to your Google Account.
If you don't already have one, sign up for a new account.
-
In the Cloud Console, on the project selector page, select or create a Google Cloud project.
-
Projeniz için faturalandırmanın etkinleştirildiğinden emin olun.
- In the Cloud Console, go to the VM Instances page.
- Click Create instance.
-
Set Name to
sendgrid-tutorial
. - In the Boot disk section, click Change to begin configuring your boot disk.
-
On the OS images tab, choose a Debian or CentOS image.
- Click Select.
- Click Create to create the instance.
- Use the Google Cloud Marketplace to sign up for the SendGrid email service. Make a note of your SendGrid SMTP account credentials, which include username, password, and hostname. Your SMTP username and password are the same as what you used to sign up for the service. The SendGrid hostname is smtp.sendgrid.net.
- Create an API key:
- Sign in to Sendgrid and go to Settings > API Keys.
- Create an API key.
- Select the permissions for the key. At a minimum, the key will need Mail send permissions to send email.
- Click Save to create the key.
- SendGrid generates a new key. This is the only copy of the key so make sure to copy the key and save it for later.
Sending mail with Postfix on your instance
Follow these steps to connect to your sendgrid-tutorial instance and run SendGrid with Postfix.
Connect to your sendgrid-tutorial instance using SSH
- In the Cloud Console, go to the VM instances page.
- In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.
Configuring SendGrid as an SMTP relay with Postfix
Run the following commands in your SSH terminal to use SendGrid as an SMTP relay with Postfix.
Become a superuser:
sudo su -
Set a safe unmask:
umask 077
Install the Postfix Mail Transport Agent:
Debian
apt-get update && apt-get install postfix libsasl2-modules -y
CentOS
yum install postfix cyrus-sasl-plain cyrus-sasl-md5 -y
If prompted, select the Local Only configuration and accept the default domain name.
Modify the Postfix configuration options. Open
/etc/postfix/main.cf
for editing. For example, to use thenano
text editor, enter the following command:nano /etc/postfix/main.cf
Update the file:
Comment out the following lines:
# default_transport = error # relay_transport = error
Add the following lines to the end of the file:
relayhost = [smtp.sendgrid.net]:2525 smtp_tls_security_level = encrypt smtp_sasl_auth_enable = yes smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd header_size_limit = 4096000 smtp_sasl_security_options = noanonymous
The above lines enforce SSL/TLS support and configure SMTP authentication for these requests. A simple access and security layer (SASL) module handles authentication in the Postfix configuration.
Save and close the file.
Generate the SASL password map using the API key you generated in the Before you begin section:
echo [smtp.sendgrid.net]:2525 apikey:[YOUR_API_KEY] >> /etc/postfix/sasl_passwd
where
[YOUR_API_KEY]
is the API key you generated.Use the
postmap
utility to generate a.db
file:postmap /etc/postfix/sasl_passwd
Verify that you have a
.db
file:ls -l /etc/postfix/sasl_passwd*
-rw------- 1 root root ... /etc/postfix/sasl_passwd -rw------- 1 root root ... /etc/postfix/sasl_passwd.db
Remove the file containing your credentials because it is no longer needed:
rm /etc/postfix/sasl_passwd
Set the permissions on your
.db
file and verify that the other file was removed:chmod 600 /etc/postfix/sasl_passwd.db ls -la /etc/postfix/sasl_passwd.db
-rw------- 1 root root ... /etc/postfix/sasl_passwd.db
Reload your configuration to load the modified parameters:
Debian
/etc/init.d/postfix restart
CentOS
postfix reload
Install the
mailutils
ormailx
package:Debian
apt-get install mailutils -y
CentOS
yum install mailx -y
Send a test email:
echo '[MESSAGE]' | mail -s [SUBJECT] [EMAIL@EXAMPLE.COM]
where:
[MESSAGE]
is the body of the email.[SUBJECT]
is the subject of the email.[EMAIL@EXAMPLE.COM]
is the email address that you want to send a message to.
Look in your system logs for a status line containing
status
and the successful server response code(250)
:Debian
tail -n 5 /var/log/syslog
CentOS
tail -n 5 /var/log/maillog
Sending mail with Java on your instance
Connect to your sendgrid-tutorial instance using SSH
- In the Cloud Console, go to the VM instances page.
- In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.
Construct and send an email message
The following instructions use the SendGrid Java client library to construct and send an email message through SendGrid. You can view the full example on GitHub.
In your SSH terminal:
Become a superuser and set a safe umask:
sudo su - umask 077
Install Java and Maven:
apt-get update -y && apt-get install git-core openjdk-8-jdk maven -y
Clone the GitHub repo:
git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
Go to the main source code for the example:
cd /root/java-docs-samples/compute/sendgrid/src/main/java/com/example/compute/sendgrid
Open
SendEmailServelet.java
for editing.Replace
YOUR-SENDGRID-API-KEY
with the API key for your SendGrid account.Replace
YOUR-SENDGRID-FROM-EMAIL
with the email address you you want to send mail from.Replace
DESTINATION-EMAIL
with the email address you want to send mail to.
Go to the root directory of the sample code:
cd /root/java-docs-samples/compute/sendgrid
Package the Java class:
mvn clean package
Go to the new
target
directory:cd target
Set permissions to allow you to execute the jar file:
chmod +x compute-sendgrid-1.0-SNAPSHOT-jar-with-dependencies.jar
Run the alternative Java version selector:
update-alternatives --config java
Select the
java-8-openjdk-amd64
option.Execute the Java file:
java -jar compute-sendgrid-1.0-SNAPSHOT-jar-with-dependencies.jar
Sending mail with Node.js on your instance
To run this sample, you must have Node.js version 7.6 or later installed on the VM instance.
Connect to your sendgrid-tutorial instance using SSH
- In the Cloud Console, go to the VM instances page.
- In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.
Construct and send an email message
In your SSH terminal:
Become a superuser and set a safe umask:
sudo su - umask 077
Update your package repositories:
Debian
apt-get update
CentOS
yum update -y
Install Node.js dependencies:
Debian
apt-get install git-core curl build-essential openssl libssl-dev -y
CentOS
yum install git-core curl openssl openssl-devel -y yum groupinstall "Development Tools" -y
Install Node.js. The installation will also install npm by default:
Debian
curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash - sudo apt-get install -y nodejs
CentOS
curl --silent --location https://rpm.nodesource.com/setup_6.x | bash -
Then, install Node.js:
yum -y install nodejs
Install the SendGrid Node.js client:
npm install sendgrid
Clone the sample repository:
git clone https://github.com/googleapis/nodejs-compute.git
Go to the directory that contains the SendGrid sample:
cd nodejs-compute/samples
Copy the
sendgrid.js
file:cp sendgrid.js sendmail.js
Open
sendmail.js
for editing.Replace
<your-sendgrid-api-key>
with the API key for your SendGrid account.Replace
from_email@example.com
with the email address that you want to send mail from.Replace
to_email@example.com
with the email address that you want to send mail to.
Execute the program to send an email message through SendGrid:
node sendmail.js
Cleaning up
To avoid incurring charges to your Google Cloud Platform account for the resources used in this tutorial:
Delete the project
The easiest way to eliminate billing is to delete the project that you created for the tutorial.
To delete the project:
- In the Cloud Console, go to the Manage resources page.
- In the project list, select the project you want to delete and click Delete delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Delete your Compute Engine instance
To delete a Compute Engine instance:
- In the Cloud Console, go to the VM Instances page.
-
Click the checkbox for
your
sendgrid-tutorial
instance. - Click Delete delete to delete the instance.
What's next
Try out other Google Cloud Platform features for yourself. Have a look at our tutorials.