updated May 6, 2020
gmail is one of the most popular email services to date, and you most likely want to use it as a mailbox for your web or mobile app. it is secure and credible, which is crucial to prevent your emails from going to the spam folder. that’s why we decided to develop how to send emails with gmail api.
gmail api: why you should consider using it
the api gives you easy access to the functions you normally have with gmail:
- send and receive html emails
- send and receive emails with attachments
- raw operations (create, read, update and delete) with messages, drafts, threads, and tags
- access control of your gmail inbox
- full web UI search capabilities
- make specific queries
- and many more…
Developers love the gmail api because it’s easy to implement. We’ll talk about that a bit later. additionally, you can use this option for versatile cases like:
- automated email sending
- mail backup
- mail migration from other email services
resource types and methods
With the gmail api, you can handle various types of resources and manage them using the following methods:
how to make your app send email with gmail api
step 1: create a project in the google api console
If you want to access your gmail from your mobile or web app, you need to start with the google developer console. first-time visitors to this page will need to accept the terms of service and choose their country of residence. then click select a project and create a new one.
give your new project a name and press create at the bottom.
step 2: enable gmail api
Once that’s done, you can hit the library tab on the left and find yourself on the api library page. enter “gmail api” in the search bar and click on it once you find it. now, you need to enable the api for your project.
Note that you will have to enable it separately for each new project you work on.
step 3: credentials and authentication with oauth 2.0
once the api is enabled, you’ll get a nice panel that says: “to use this api, you may need credentials”. If you click create credentials, you will be asked a series of questions to find out what type of credentials you need. We advise you to go the other way since we know what it is: oauth client id. so click on the credentials tab on the left and then choose the authentication client id from the create credentials button drop down list.
you will see the settings button on the consent screen. It will take you to a page with many fields. you can only enter the name of your application and specify the authorized domains. Fill in other fields if you want.
click save and then choose the type of your app (web app, android, chrome app, ios or other). after that name your oauth client id. Also, enter the javascript origins and redirect domains to use with requests from a browser or a web server, respectively. click create to finish. that is all. download a json file with your credentials; you will need it later.
step 4: choose a quick start guide
The next step is to select a quick start guide based on the technology your application was built with. So far, there are the following options:
- api to go
- api to java
- api to ruby
- api to .net
- api to node .js
- api for php
- api for python
- api for browser (javascript)
for mobile apps, there are also g suite apis for ios and android.
The first thing you need in this quickstart is the prerequisites section. let’s say your choice is php. in this case make sure your php version corresponds to the one given. also, install the json extension and composer dependency management tool if you haven’t already. after that you can install google client library. for java, you will need to create a new project structure and directory src/main/resources/. then copy the json file with the credentials to this directory and replace the content of the build.gradle file with this code. so pay attention when preparing your project.
route your test emails to mailtrap for secure testing.
step 5: api client library
google provides client libraries to work with the api:
api client for go
api client for java
api client for ruby
api client for .net
api client for node.js
api client for php
api client for python
step 6: access to gmail
In this step, we need to authorize access to your gmail account from the app and then you can manage emails. for this you need to create a file in your working directory. below you will find the specific file names for each technology. copy and paste a corresponding code sample from the chosen quickstart and run it. here are the links to the code examples:
go
- filename: quickstart.go
- directory: gmail/quickstart/
- code sample to go
- run with: go run quickstart.go
java
- flinename: gmailquickstart.java
- directory: src/main/java/
- code sample for java
- run with: gradle run
ruby
- filename: quickstart.rb
- directory: gmail/quickstart/
- code sample for ruby
- run with: ruby quickstart.rb
.net
- filename: gmailquickstart.cs
- directory: gmail/gmailquickstart/
- code sample for .net
- run by clicking start in the visual studio toolbar
node.js
- filename: index.js
- directory: gmail/quickstart/
- code sample for node.js
- run with: node .
php
- filename: quickstart.php
- directory: gmail/quickstart/
- code sample for php
- run with: php quickstart .php
python
- filename: quickstart.py
- directory: gmail/quickstart/
- code sample for python
- run with: python quickstart .py
javascript (browser)
- filename: index.html
- directory: gmail/quickstart/
- browser code example (javascript)
- replace < ;your_client_id> with your client id and <your_api_key> with your api key. run with:
- python -m simplehttpsserver 8000 – for python 2+
- python -m http.server 8000 – for python 3+
it worked… or it didn’t. google will warn you about a likely failure of the sample you run to open a new window in your default browser. if this happens, you will have to do it manually. copy the url from the console and paste it in the browser. will look like this:
You will then be prompted to sign in to your google account or select an account for authorization. press allow and you will see all your inbox labels in the ssh shell like this:
congratulations! gmail api works and you can send your first email.
step 7: create an email
To send a message, you must first create one. for this, your application can use the drafts.create method which includes:
- creating a mime message
- converting the message to a base64url-encoded string
- creating a draft
let’s see how this is done in practice with python:
and php
test your emails now
step 8: send an email
Once you’ve created your message, you can call message.send or drafts.send to send it. this is how it can look:
python
and php
step 8.1: send an email with attachments
You can also create and send a multipart mime message. for example, this is how it looks with python:
test your emails before sending them to real users.
Step 9: Read a specific email from your inbox
It would be weird if you couldn’t use the api to read gmail messages. luckily you can use the get method for the message id. this is how it can look like in a python application:
if the message contains an attachment, expand your code with the following:
why is gmail api better or worse than traditional smtp?
email protocol used
simple mail transfer protocol (smtp) is a set of rules for sending email from the sender to the email server or between servers. most email service providers use smtp to send and pop3/imap4 to receive emails. To learn more about these protocols, you can read our imap vs. pop3 vs. smtp. Google also provides the gmail smtp server as a free smtp service. Application Programming Interface (API) is an interaction channel used by applications, platforms, and code to communicate with each other. With the Gmail API, you can send email using only the Hypertext Transfer Protocol (HTTP), a set of rules that defines how messages are formatted and transmitted.
how are emails sent?
you can call the api from the application to communicate with an email service that is used to send email from another server.
for smtp, a client establishes a tcp connection with the smtp server and transfers an email. after authorization, the server sends the email to the recipient’s smtp server, which, in turn, forwards it to the imap4 or pop3 server. the client and server communicate with each other using smtp commands and responses.
authentication
The gmail api uses open authentication (oauth2), which only allows you to request the scope of access you need. smtp provides full account access via client login and password smtp authentication.
quota
the gmail api usage limit is one billion quota units per day. each method requires a particular number of quota units. for example, a drafts.create is 10 units and a message.send is 100 units. gmail api enforces standard daily mail sending limits. Also, note that the maximum email size in Gmail is 25MB.
smtp or api?
Each option has its pros and cons. smtp is a widely adopted and easy to configure solution for sending email. plus, you don’t need any coding skills to handle things. Additionally, you can benefit from using a fake smtp server like mailtrap as a playground for secure email testing.
In addition, it is a great option to automate processes and provide a wide range of functionalities for the application. Furthermore, API can boast an additional level of security, which is crucial when it comes to sending sensitive data in emails.