Postmark Email Agents

This is a submission for the Postmark Challenge: Inbox Innovators.

What I Built

I built "Postmark Email Agents," a powerful email processing application that intelligently handles incoming emails to automate tasks and organize your digital life. The system receives emails through Postmark webhooks, analyzes their content using a suite of AI agents, and automatically identifies and processes actionable items.

Whether it's an event to be added to your calendar, a shipping notification for a recent purchase, or important information that needs to be saved as a note, our application handles it all. It's designed to turn a cluttered inbox into a structured, automated workflow, making sure you never miss an important task hidden within an email.

Demo

Frontend is not ready yet

Code Repository

The full source code for this project is available on GitHub:
GitHub Repository

How I Built It

The application is built with a modern, scalable architecture using Python and FastAPI. Here's a breakdown of the implementation process and technology stack.

Implementation Process

The development process was centered around a modular, decoupled architecture to ensure maintainability and extensibility.

1. Foundation with FastAPI: I started by setting up a FastAPI application to serve as the backbone for the API. This included configuring versioned routes, CORS middleware, and a static file server for attachments.

2. Email Processing Pipeline: The core of the application is the email processing pipeline. I implemented a WebhookProcessingService that listens for incoming Postmark webhooks. This service is responsible for:

   • Receiving and storing the raw email JSON for reliability.
   • Parsing the email content, headers, and attachments.
   • Organizing emails into conversation threads.
   • Saving attachments to the file system and making them accessible via a URL.

3. AI-Powered Actionables Module: The most innovative part of the project is the actionables module. I designed a multi-agent system using a Pydantic AI Agents framework. This is how it works:

   • An Agent Orchestrator processes the content of each new email.
   • It uses specialized agents, each defined by a Pydantic model, to look for specific types of information. For example, the CalendarAgent has a Pydantic model that defines fields like event_name, date, and attendees.
   • The orchestrator sends the email text and the Pydantic schemas to a LLM (Gemini 2.5 Flash), using its function-calling ability to extract structured data.
   • If the LLM successfully populates an agent's Pydantic model, the orchestrator triggers the corresponding action, like adding an event to a calendar. This design makes it incredibly easy to add new agents for new tasks without changing the underlying system.

4. Database and Data Access: I used PostgreSQL as the database and SQLAlchemy as the ORM. The repository pattern was implemented to abstract database logic from the business logic, making the code cleaner and easier to test.

Technology Stack

• Backend: Python, FastAPI
• Database: PostgreSQL
• ORM: SQLAlchemy
• Data Validation: Pydantic
• AI/Agents: PyDantic AI Agents
• Email Service: Postmark (for inbound email processing via webhooks)

Experience with Postmark

Postmark was a pleasure to work with. The webhook integration was straightforward, and the documentation was clear and comprehensive. The detailed JSON payload provided for each email made it easy to parse and extract all the necessary information, from headers and body content to attachments. The reliability of the webhook delivery was crucial for the success of this project.