This helper is a stand-alone module to help get you started consuming and processing Inbound Parse data.

Table of Contents

Quick Start for Local Testing with Sample Data
Quick Start for Local Testing with Real Data
Deploy to Heroku
Code Walkthrough
Testing the Source Code
Contributing

Quick Start for Local Testing with Sample Data

git clone https://github.com/sendgrid/sendgrid-python.git
cd sendgrid-python
pip install -r requirements.txt

Run the Inbound Parse listener in your terminal:

python sendgrid/helpers/inbound/app.py

In another terminal, run the test data sender:

cd [path to sendgrid-python]
pip install -r requirements.txt
python sendgrid/helpers/inbound/send.py ./sendgrid/helpers/inbound/sample_data/default_data.txt

More sample data can be found here.

View the results in the first terminal.

Quick Start for Local Testing with Real Data

Setup your MX records. Depending on your domain name host, you may need to wait up to 48 hours for the settings to propagate.

Run the Inbound Parse listener in your terminal:

git clone https://github.com/sendgrid/sendgrid-python.git
cd sendgrid-python
pip install -r requirements.txt
python sendgrid/helpers/inbound/app.py

In another terminal, use ngrok to allow external access to your machine:

ngrok http 5000

Update your SendGrid Incoming Parse settings: Settings Page | Docs

For the HOSTNAME field, use the domain that you changed the MX records (e.g. inbound.yourdomain.com)
For the URL field, use the URL generated by ngrok + /inbound, e.g http://XXXXXXX.ngrok.io/inbound

Next, send an email to [anything]@inbound.yourdomain.com, then look at the terminal where you started the Inbound Parse listener.

Deploy to Heroku

Get a Heroku account.

Setup your MX records. Depending on your domain name host, you may need to wait up to 48 hours for the settings to propagate.

Update your SendGrid Incoming Parse settings: Settings Page | Docs

For the HOSTNAME field, use the domain that you changed the MX records (e.g. inbound.yourdomain.com)
For the URL field, use the URL generated by Heroku + /inbound, e.g https://[name-of-your-app].herokuapp.com/inbound

Next, send an email to [anything]@inbound.yourdomain.com, then look at your Heroku logs: https://dashboard.heroku.com/apps/[name-of-your-app]/logs

While you are waiting for your MX records to propagate, you can test by using the test data sender:

git clone https://github.com/sendgrid/sendgrid-python.git
cd [path to sendgrid-python]
pip install -r requirements.txt
python sendgrid/helpers/inbound/send.py ./sendgrid/helpers/inbound/sample_data/default_data.txt -host https://[name-of-your-app].herokuapp.com/inbound

To make changes: clone, modify and push the changes.

For example:

git clone https://github.com/sendgrid/sendgrid-python.git 
heroku git:remote -a [name-of-your-app]
---make changes---
git add .
git commit -m "update configuration"
git push heroku main

Code Walkthrough

app.py

This module runs a Flask server, that by default (you can change those settings here), listens for POSTs on http://localhost:5000. When the server receives the POST, it parses and prints the key/value data.

config.py & config.yml

This module loads credentials (located in an optional .env file) and application environment variables (located in config.yml).

parse.py

This module parses the incoming POST data from a Flask request object containing POSTed data from the SendGrid Incoming Parse webhook.

send.py & /sample_data

This module is used to send sample test data. It is useful for testing and development, particularly while you wait for your MX records to propagate.

Testing the Source Code

Tests are located in the root of this project in the /test folder:

Learn about testing this code here.

Contributing

If you would like to contribute to this project, please see our contributing guide. Thanks!