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

What I Built

view highres architectural diagram

I built CCMyJira, an AI-powered, multi-tenant SaaS platform that intelligently transforms emails into structured, actionable JIRA tickets. It bridges the communication gap between email-centric clients/users and JIRA-focused development teams.

The Core Problem: Critical requests, bug reports, and feedback in emails often get lost, misinterpreted, or require manual, error-prone transcription into JIRA, leading to inefficiencies and delays.

CCMyJira's Solution – Key Capabilities:

Essentially, CCMyJira acts as an intelligent automation layer, ensuring every important email becomes an actionable JIRA item, with Postmark as the crucial email gateway.

Demo

Watch the Video Demo:

Experience CCMyJira live: ccmyjira.com

We offer two ways to explore the platform's capabilities:

1. 🚀 Instant Demo (No Atlassian Account Needed)

This mode lets you see the core email-to-ticket functionality in action immediately using a shared demo JIRA board.

What you'll see:
An email transformed into a JIRA ticket in a Kanban view:

(note that in demo mode, you can't directly access the Jira links because they can't be public, therefore I built a custom API to fetch Jira tickets and view attachments)

2. 🔒 Full SaaS Experience (With Your Atlassian Account)

This mode demonstrates the complete multi-tenant SaaS flow, connecting CCMyJira to your own Atlassian JIRA instance.

Kanban View within CCMyJira:
Once tickets are processed, you can view them in JIRA or the Kanban view:

Testing Tips:

• Complex Emails: Try sending emails with mixed content: inline images, multiple attachments (PDFs, logs, text files), HTML formatting, and long discussion threads.
• Keywords: Use keywords that might imply priority (e.g., "urgent," "critical") or ticket type (e.g., "bug report," "feature request").
• Mentions: If you've set up users in your JIRA project, try @mentioning a user in the email body.
• Follow-ups: Reply to the original email thread (ensuring [email protected] is a recipient). The AI should identify it as a follow-up and update the existing JIRA ticket.

Code Repository

The project is split into two main repositories:

1. Server-Side Application (Backend):
   • This repository contains all the NestJS backend logic, including the AI agent, JIRA integration, Postmark webhook handling, multi-tenancy features, queue management, and API endpoints. The comprehensive documentation (/docs folder) detailing the architecture and features resides here.

1. Website & Dashboard (Frontend):
   • This repository contains the Next.js/React frontend application, which includes the user onboarding, dashboard for viewing processed tickets, organization management, and domain verification UI.

git clone https://github.com/youneslaaroussi/ccmyjira-site.git
cd ccmyjira-site

bun install

cp env.example .env.local

NEXT_PUBLIC_API_BASE_URL=http://localhost:3001

bun dev

How I Built It

view highres smart assignment diagram

Building CCMyJira was an exploration into creating a deeply integrated system where email, AI, and project management converge to streamline workflows. The mission was clear: make emails first-class citizens in JIRA, intelligently.

The Core Idea: Intelligent Email-to-JIRA Automation

The project stemmed from the universal challenge of critical information shared via email often being siloed or requiring tedious manual effort to integrate into project management tools like JIRA. I aimed to not just automate this but to infuse it with intelligence to understand context, prevent redundancy, and ensure tasks are actionable.

The agent has access to some of these tools:

{
  name: 'get_current_period',
  description: 'Get current date and time information'
}

{
  name: 'read_jira_tickets',
  description: 'Read JIRA tickets from a specific time period',
  parameters: {
    days: 'Number of days to look back',
    status: 'Filter by ticket status',
    assignee: 'Filter by assignee',
    searchText: 'Search in summary/description'
  }
}

{
  name: 'create_jira_ticket',
  description: 'Create a new JIRA ticket. Email attachments and embedded images are automatically included.',
  parameters: {
    summary: 'Ticket title/summary',
    description: 'Detailed description. Email context will be automatically appended.',
    issueType: 'Bug, Story, Task, Epic, etc.',
    priority: 'Highest, High, Medium, Low',
    assignee: 'Username or email to assign',
    labels: 'Array of labels to add',
    components: 'Array of component names'
  }
}

{
  name: 'modify_jira_ticket',
  description: 'Modify an existing JIRA ticket. New email attachments and embedded images are automatically added.',
  parameters: {
    ticketKey: 'JIRA ticket key (e.g., PROJ-123)',
    summary: 'New summary (optional)',
    status: 'New status (optional)',
    assignee: 'New assignee (optional)',
    comment: 'Add comment. Email context will be automatically appended. (optional)'
  }
}

Leveraging Postmark for Robust Email Processing

Postmark was instrumental, serving as the reliable and developer-friendly gateway for all email interactions.

• Inbound Email Parsing – The Heart of the System: CCMyJira's ability to process emails begins with Postmark. Emails sent to [email protected] are received and meticulously parsed by Postmark. The resulting rich JSON payload, complete with attachments, HTML/text bodies, and headers, is then dispatched via webhook to our NestJS API endpoint (/webhooks/postmark). This structured data is the fuel for our AI engine.
• Critical: Immediate Webhook Response & Asynchronous Processing: A cornerstone of the architecture (detailed in README.md and docs/01-architecture.md) is the immediate 200 OK response (target <100ms) to Postmark webhooks. The intensive AI processing and JIRA API communications (often 15-60+ seconds) are deferred to background jobs managed by BullMQ and Redis. This design is vital as it prevents Postmark webhook timeouts, ensuring no email is lost and maintaining system responsiveness and scalability.
• Outbound Email for Operational Integrity: Beyond inbound, Postmark handles essential outbound communications. Most significantly, it sends domain verification emails (as outlined in docs/15-domain-verification-guide.md). This Postmark-powered step is crucial for the multi-tenant security model, allowing organizations to securely link their email domains to their JIRA instances.
• Professional Presence with Custom Domains: Postmark facilitates the use of CCMyJira's own inbound domain (send.ccmyjira.com) and a verified sender domain ([email protected]), enhancing trust and brand consistency for users.

Postmark's reliability, comprehensive API, and clear documentation for both inbound parsing and outbound sending were pivotal, allowing me to focus on the application's core intelligence.

Tech Stack

Key Implementation Details & Architectural Decisions

CCMyJira's effectiveness stems from several core architectural choices:

1. Postmark-Driven Asynchronous Processing: To ensure reliability with Postmark, incoming emails trigger a rapid 200 OK response. The actual complex processing (AI analysis, JIRA updates) is then handled by a robust background queue system (BullMQ/Redis). This prevents Postmark webhook timeouts and allows the system to gracefully manage email bursts.

2. Sophisticated AI Agent (docs/04-ai-agent.md):

   • Iterative Intelligence: Uses multi-step GPT-4o conversations to understand email context deeply, search JIRA for existing issues (preventing duplicates), and then decide on the best action (create, update, comment).
   • Comprehensive Data Handling: Processes and attaches all email content, including files and embedded images, directly to JIRA tickets.
   • High-Quality Ticket Creation: AI is guided to create well-structured, professional JIRA tickets (see docs/improved-ticket-example.md) that are immediately actionable, a significant step up from raw email dumps.
   • Smart Assignments: Suggests appropriate JIRA users for tickets based on workload, skills, and email content (like @mentions).

3. **Secure & Scalable Multi-Tenancy (docs/13-multi-tenant-architecture.md):

   • Seamless Onboarding: Users connect via Atlassian OAuth, securely linking their JIRA instances.
   • Postmark-Secured Domain Verification: Organizations verify domain ownership using a Postmark-sent confirmation email. Only emails from verified domains are routed to a tenant's JIRA, ensuring emails go to the correct organization.
   • Data Isolation: Supabase RLS strictly separates each organization's data.
   • Targeted Email Routing: A dedicated service maps incoming email domains to the correct tenant, applying their specific JIRA and AI settings.

4. Production-Ready Design:

   • Comprehensive Documentation: The project is backed by extensive documentation covering architecture, setup, and APIs.
   • Dockerized: For consistent environments from development to production.
   • Large Payload Support: Engineered to handle large emails with multiple attachments (up to 10MB).
   • Modular & API-First: Promotes maintainability and clear separation of concerns.

Experience with Postmark

My experience integrating Postmark was exceptionally positive and fundamental to CCMyJira's success. Postmark effectively solved the critical first step: getting email content into the application reliably and in a structured format.

• Developer-Friendly Inbound Parsing: Postmark's webhook setup was straightforward, and the parsed email JSON was rich and easy to work with. This was the primary Postmark feature utilized and it formed the very foundation of the application.
• Reliability & Peace of Mind: Knowing Postmark handles the complexities of email reception and parsing (with webhook retries) allowed me to focus on the core AI and JIRA integration logic.
• Excellent Documentation: Clear guides and API references accelerated development significantly.
• Efficient Testing: The ability to quickly test the inbound flow was invaluable for iteration.
• Built for Scale: The webhook architecture, paired with our asynchronous processing, ensures the system is ready for high email volumes.

Postmark's inbound parsing was not just a feature used; it was the enabling technology that made CCMyJira feasible. It elegantly abstracts the complexities of email handling, empowering developers to build innovative email-driven applications like this one.

Developed by Younes Laaroussi.