A FastAPI-based webhook handler that transforms email into a natural interface for AI interaction. Using SendGrid's Inbound Parse, it enables users to communicate with a Langflow AI agent through their regular email client.
The Langflow AI agent configuration showing the email processing and response generation flow
Want to interact with our AI agent? It's as simple as sending an email:
📧 Email Address: [email protected]
The service will process your email and respond with an AI-generated reply. Try asking questions, requesting analysis, or starting a conversation!
Our AI email interface can handle various types of requests. Simply send your email to [email protected] for any of these capabilities:
- 🛍️ Deals and Shopping - Find the latest deals and compare prices across retailers
✈️ Travel Planning - Get personalized recommendations for restaurants, activities, and locations with map links- 💹 Financial Information - Track company performance and market trends in real-time
- 📚 Research Assistant - Get comprehensive analysis on academic or technical topics
Email AI Agent Interface
.----------.
/ /|
/ EMAIL / |
/ /@\ / |
.----------. |
| | |
| | /
| | /
.----------.
|
v
+--------------+
| WEBHOOK |
| HANDLER |---> [Parse]
| |---> [Clean]
+--------------+---> [Extract]
|
v
+--------------+
| AI AGENT |====> Natural
| PROCESSOR |====> Language
| </> |====> Response
+--------------+
|
v
[ Smart Response ]
This service acts as a bridge between SendGrid's Inbound Parse webhook and your Langflow AI agent. It:
- Receives webhook payloads from SendGrid's Inbound Parse
- Cleans and sanitizes the email data
- Extracts relevant information (sender, subject, message text, thread IDs)
- Forwards the cleaned data to a Langflow endpoint for AI processing
- 🚧 Coming Soon: File attachment handling (images, documents, etc.) - In Development
Our service is built on a modern, robust technology stack:
- Python 3.12+ - Latest Python version with improved performance and features
- FastAPI - Modern, fast web framework for building APIs with Python
- Langflow - Open-source LangChain Flow implementation for AI agent orchestration
- SendGrid - Email delivery and webhook processing platform
- email-reply-parser - Intelligent email thread parsing
- python-dotenv - Environment variable management
- uvicorn - Lightning-fast ASGI server implementation
- pytest - Testing framework for robust test coverage
- flake8 - Code linting and style guide enforcement
- black - Code formatting for consistent style
The following environment variables are required:
LOG_LEVEL: Logging level (default: INFO)PORT: Server port (default: 8000)LANGFLOW_API_URL: Base URL for Langflow APILANGFLOW_ENDPOINT: Specific Langflow endpoint to callLANGFLOW_API_KEY: Optional API key for secured endpoints
-
Copy the example environment file:
cp .env.example .env
-
Edit the
.envfile with your specific configuration:# Server Configuration PORT=8000 LOG_LEVEL=INFO # Langflow Configuration LANGFLOW_API_URL=http://localhost:3000 # Your Langflow instance URL LANGFLOW_ENDPOINT=your-flow-endpoint # Your specific flow endpoint LANGFLOW_API_KEY=your-api-key # Optional: Your API key
Receives incoming webhook POST requests from SendGrid's Inbound Parse.
Input Fields:
to: Recipient email addresssender: Sender email address (alias: "from")subject: Email subjecttext: Email body textheaders: Raw email headers
Response:
- Success:
{"status": "accepted"} - Error:
{"status": "error", "message": "..."}
Health check endpoint to verify service status.
Response:
{"status": "healthy"}
- Email Thread Parsing: Extracts and tracks email conversation threads using email-reply-parser
- Reply Extraction: Intelligently extracts reply content from email chains
- Unicode Normalization: Ensures consistent character encoding
- Async Processing: Background task handling using FastAPI's async features
- Python 3.12+ (developed and tested with Python 3.12.5)
- pip
-
Clone this repository:
git clone https://github.com/SonicDMG/email_agent_interface.git cd email_agent_interface -
Install dependencies:
pip install -r requirements.txt
To test the webhook locally, you'll need to make your local server accessible to SendGrid. We recommend using ngrok for this:
-
Install ngrok:
# Using Homebrew (macOS) brew install ngrok # Using npm npm install ngrok -g # Or download directly from https://ngrok.com/download
-
Start your FastAPI server:
python -m uvicorn webhook_handler:app --reload --port 8000
-
In a new terminal, create an ngrok tunnel:
ngrok http 8000
-
Copy your ngrok URL (looks like
https://xxxx-xx-xx-xxx-xx.ngrok.io) -
Configure SendGrid:
- Go to SendGrid's Inbound Parse Settings
- Add a new domain or subdomain
- Set the URL to your ngrok URL +
/webhook(e.g.,https://xxxx-xx-xx-xxx-xx.ngrok.io/webhook) - Save the settings
Now emails sent to your configured SendGrid address will be forwarded to your local development server through ngrok.
SendGrid configuration showing the webhook URL (/webhook endpoint) for local testing
Ngrok console displaying the forwarded traffic to your local webhook endpoint
The images above show:
- SendGrid's webhook configuration pointing to your ngrok URL +
/webhook - Ngrok's console showing the incoming webhook requests being forwarded to your local server
Notice how the SendGrid Inbound Parse webhook address matches the address generated by ngrok, ensuring that incoming emails are correctly forwarded to your local development environment.
Note: The free tier of ngrok will generate a new URL each time you restart the tunnel. You'll need to update your SendGrid webhook URL accordingly. For persistent URLs, consider upgrading to a paid ngrok plan.