**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_local_sample)
* [Quick Start for Local Testing with Real Data](#quick_start_local_real)
* [Deploy to Heroku](#heroku)
* [Code Walkthrough](#code_walkthrough)
* [Testing the Source Code](#testing)
* [Contributing](#contributing)

<a name="quick_start_local_sample"></a>
# Quick Start for Local Testing with Sample Data

```bash
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
python sendgrid/helpers/inbound/app.py
```

In another terminal, run the test data sender:

```bash
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](https://github.com/sendgrid/sendgrid-python/tree/master/sendgrid/helpers/inbound/sample_data).

View the results in the first terminal.

<a name="quick_start_local_real"></a>
# Quick Start for Local Testing with Real Data

[Setup your MX records.](https://sendgrid.com/docs/Classroom/Basics/Inbound_Parse_Webhook/setting_up_the_inbound_parse_webhook.html#-Setup) 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:

```bash
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](https://ngrok.com/) to allow external access to your machine:
```bash
ngrok http 5000
```

Update your SendGrid Incoming Parse settings: [Settings Page](https://app.sendgrid.com/settings/parse) | [Docs](https://sendgrid.com/docs/Classroom/Basics/Inbound_Parse_Webhook/setting_up_the_inbound_parse_webhook.html#-Pointing-to-a-Hostname-and-URL)

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

<a name="heroku"></a>
# Deploy to Heroku

Get a [Heroku](https://www.heroku.com) account.

[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/sendgrid/sendgrid-python/tree/master)

[Setup your MX records.](https://sendgrid.com/docs/Classroom/Basics/Inbound_Parse_Webhook/setting_up_the_inbound_parse_webhook.html#-Setup) 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](https://app.sendgrid.com/settings/parse) | [Docs](https://sendgrid.com/docs/Classroom/Basics/Inbound_Parse_Webhook/setting_up_the_inbound_parse_webhook.html#-Pointing-to-a-Hostname-and-URL)

- 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:

```bash
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:
```bash
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 master
```

<a name="code_walkthrough"></a>
# Code Walkthrough

## app.py

This module runs a [Flask](http://flask.pocoo.org/docs/0.11/) server, that by default (you can change those settings [here](https://github.com/sendgrid/sendgrid-python/blob/inbound/sendgrid/helpers/inbound/config.yml)), 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](https://github.com/sendgrid/sendgrid-python/blob/inbound/sendgrid/helpers/inbound/config.yml)).

## parse.py

This module parses the incoming POST data from a [Flask request object](http://flask.pocoo.org/docs/0.11/api/#flask.request) 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.

<a name="testing"></a>
# Testing the Source Code

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

- [test_config.py](https://github.com/sendgrid/sendgrid-python/blob/master/test/test_config.py)
- [test_parse.py](https://github.com/sendgrid/sendgrid-python/blob/master/test/test_parse.py)

Learn about testing this code [here](https://github.com/sendgrid/sendgrid-python/blob/master/CONTRIBUTING.md#testing).

<a name="contributing"></a>
# Contributing

If you would like to contribute to this project, please see our [contributing guide](https://github.com/sendgrid/sendgrid-python/blob/master/CONTRIBUTING.md). Thanks!
