Create your own Mail API based on Google App Engine (GAE) with 99.95% uptime SLA.
This Mail API make integrating email into your existing applications easy with your own RESTful API. It is developed in Python 3 and uses the Google App Engine API for legacy bundled services.
Make API calls to emails:
- Clone this repo
git clone https://github.com/Cyclenerd/google-cloud-appengine-mail-api.git cd google-cloud-appengine-mail-api
- Deploy app to App Engine
gcloud config set project PROJECT_ID gcloud app deploy
- Create new Google Cloud Secret Manager secret
gcloud auth application-default login terraform init terraform apply
- Generate and store API password (without newline)
openssl rand -hex 25 | tr -d \\n | gcloud secrets versions add "api-password" \ --data-file=-
- Access API password
gcloud secrets versions access latest --secret="api-password"
Optional:
You can set the mail sender (email address for From header) with the environment variable SENDER
in app.yaml.
Default sender is [PROJECT_ID] <no-reply@[PROJECT_ID].appspotmail.com>
.
Authentication to the Mail API is done by providing an Authorization header using HTTP Basic Auth; use api
as the username and your secret API password as the password.
Here is how you use basic HTTP auth with curl:
curl --user 'api:YOUR_API_PASSWORD'
Warning Keep your API password secret!
The Mail API returns standard HTTP response codes.
Code | Description |
---|---|
201 | Everything worked as expected |
401 | Unauthorized - No valid API password provided |
400 | Bad Request - Often missing a required parameter |
POST https://PROJECT_ID.REGION_ID.r.appspot.com/messages
Parameter | Description |
---|---|
to | Email address of the recipient(s). Example: "Bob bob@host.com". You can use commas to separate multiple recipients. |
subject | Message subject |
text | Body of the message. (text version) |
Sending a plain text message:
curl -s --user "api:YOUR_API_PASSWORD" \
"https://PROJECT_ID.REGION_ID.r.appspot.com/messages"
-F "to=test@nkn-it.de" \
-F "subject=Test" \
-F "text=Test"
Sample response:
HTTP code: 201
Successfully sent mail to test@nkn-it.de.
π More examples (Go, PHP, Perl, Python, Ruby...)
This is a list of possible return codes and messages from the /messages
endpoint.
Code | Error message |
---|---|
400 | to parameter is missing |
400 | subject parameter is missing |
400 | text parameter is missing |
401 | Forbidden (Unauthorized access) |
405 | Method not allowed (please use POST) |
500 | Internal Server Error |
The default quota for email recipients is 100 per day. If you need a higher mail quota, you can use SendGrid or Mailgun to send email.
Have a patch that will benefit this project? Awesome! Follow these steps to have it accepted.
- Please read how to contribute.
- Fork this Git repository and make your changes.
- Create a Pull Request.
- Incorporate review feedback to your changes.
- Accepted!
All files in this repository are under the Apache License, Version 2.0 unless noted otherwise.
Portions of this repository are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 4.0 Attribution License.