Google App Engine Mail API

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:

🏃 Deploying

1. Clone this repo

   git clone https://github.com/Cyclenerd/google-cloud-appengine-mail-api.git
   cd google-cloud-appengine-mail-api

2. Deploy app to App Engine

   gcloud config set project PROJECT_ID
   gcloud app deploy

3. Create new Google Cloud Secret Manager secret

   gcloud auth application-default login
   terraform init
   terraform apply

4. Generate and store API password (without newline)

   openssl rand -hex 25 | tr -d \\n | gcloud secrets versions add "api-password" \
       --data-file=-

5. 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

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!

🆗 Status codes

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

📨 Sending

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)

Example

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...)

🆘 Error codes

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

💡 Rate Limits

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.

📚 Read more

• Sending mail with the Mail API
• Flask app to access bundled Mail services API in Python 3

❤️ Contributing

Have a patch that will benefit this project? Awesome! Follow these steps to have it accepted.

1. Please read how to contribute.
2. Fork this Git repository and make your changes.
3. Create a Pull Request.
4. Incorporate review feedback to your changes.
5. Accepted!

📜 License

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.