Skip to main content

Postchi - Product Overview

Version: 1.0 Last Updated: January 2025 Status: MVP Development

Executive Summary​

Postchi is a complete email delivery platform designed as an alternative to SendGrid and Mailgun. Built with modern technologies (Node.js, TypeScript, PostgreSQL), Postchi provides everything needed to send, track, and manage transactional and marketing emails at scale.

What Makes Postchi Different?​

  • All-in-One Platform - Email delivery, automation, contacts, and analytics in one place
  • Modern Architecture - Built with TypeScript, React, and battle-tested technologies
  • Complete Control - Full control over your email infrastructure
  • Privacy Focused - Keep your data secure and maintain full privacy

Current Feature Set​

1. Core Email Delivery​

Domain Management​

  • Multi-domain support - Add and verify multiple sending domains
  • DNS verification wizard - Step-by-step setup for SPF, DKIM, DMARC, and MX records
  • Real-time verification - Automatic DNS checking with detailed feedback
  • Domain status tracking - Monitor verification status for each domain
  • SMTP credentials - Per-domain SMTP access (coming soon)

Message Sending​

  • RESTful API - Simple HTTP API for sending emails
  • Template-based sending - Use templates with variable substitution
  • Direct sending - Send HTML/text emails directly via API
  • Batch operations - Send to multiple recipients efficiently
  • Rich content support - HTML emails, plain text fallback, attachments

Message Tracking & Logging​

  • Comprehensive logs - Complete audit trail of all sent emails
  • Delivery status tracking - Monitor queued, sent, delivered, bounced, failed states
  • Advanced filtering - Filter by status, domain, date range, recipient
  • Search functionality - Find messages by content, recipient, or metadata
  • Event timeline - Detailed event history for each message
  • Engagement metrics - Track opens and clicks (in progress)

2. Email Automation (Flows)​

Visual Flow Builder​

  • Drag-and-drop canvas - Build automation workflows visually with React Flow
  • Node-based system - Connect triggers and actions intuitively
  • Real-time preview - See your flow structure as you build

Triggers​

  • Contact added to list - Start flows when contacts join a list
  • Contact tagged - Trigger on specific tag assignments
  • Contact subscribed - Welcome new subscribers automatically
  • Manual trigger - Run flows on-demand

Actions​

  • Send email - Deliver templated or custom emails
  • Wait/Delay - Add time delays between actions
  • Add tag - Tag contacts based on behavior
  • Conditions - Branch flows based on contact data or behavior

Flow Management​

  • Draft & publish workflow - Test flows before activating
  • Version control - Track changes to your flows
  • Flow templates - Start with pre-built automation recipes
  • Status tracking - Monitor active, paused, and draft flows

3. Contact & List Management​

Contact Database​

  • Centralized contact storage - Single source of truth for all contacts
  • Custom fields - Store any contact metadata you need
  • Import/export - Bulk contact operations via CSV
  • Subscription management - Global unsubscribe handling
  • Contact source tracking - Know where each contact came from

Lists​

  • Segmentation - Organize contacts into lists
  • Multiple list membership - Contacts can belong to multiple lists
  • List statistics - See contact counts and engagement metrics
  • Dynamic updates - Add/remove contacts programmatically

Tags​

  • Flexible tagging - Label contacts with custom tags
  • Tag-based automation - Trigger flows based on tags
  • Bulk tagging - Apply tags to multiple contacts at once
  • Color coding - Visual organization with colored tags

4. Email Templates​

Template Editor​

  • Monaco code editor - Professional code editing experience
  • Syntax highlighting - HTML and plain text editing
  • Live preview - See your template as you type (coming soon)
  • Variable system - Use {{variable}} syntax for personalization
  • Dual format - HTML and plain text versions

Template Management​

  • Template library - Store and organize all your templates
  • Version history - Track template changes over time
  • Template starters - Pre-built templates for common use cases
    • Welcome emails
    • Password resets
    • Transactional receipts
    • And more...
  • Domain assignment - Control which domains can use each template
  • Test sending - Send test emails with sample data

Template Features​

  • Variable detection - Automatically identifies required variables
  • API integration - Send emails using template IDs
  • cURL examples - Copy-paste API examples for each template

5. User & Organization Management​

Multi-tenancy​

  • Organization isolation - Complete data separation between organizations
  • Team collaboration - Multiple users per organization
  • Role-based access control - Admin, Editor, Viewer roles
  • User invitations - Add team members easily

Authentication & Security​

  • JWT-based authentication - Secure session management
  • API key management - Generate multiple API keys per organization
  • Session tracking - Monitor active sessions across devices
  • Session revocation - Force logout from specific devices
  • Password management - Secure password changes

User Features​

  • User profiles - Manage name, email, and settings
  • Activity tracking - See when and where users log in
  • Device management - View sessions by device type and location

6. Analytics & Reporting​

Dashboard Overview​

  • Key metrics - Messages sent, delivery rate, open rate, click rate
  • Visual charts - Line graphs showing trends over time
  • Recent activity - Latest messages and events
  • Quick stats - At-a-glance performance indicators

Advanced Filtering​

  • Date range selection - Analyze specific time periods
  • Multi-dimensional filtering - Combine filters for precise analysis
  • Export capabilities - Download filtered data (coming soon)

7. Webhooks & Integrations​

Webhook System​

  • Event notifications - Real-time updates for email events
  • Multiple webhooks - Configure different endpoints per event type
  • Event types:
    • Email delivered
    • Email opened
    • Link clicked
    • Email bounced
    • Spam complaint
    • Unsubscribe
  • Webhook testing - Test webhook endpoints before going live
  • Retry logic - Automatic retries for failed webhook deliveries
  • Event logging - Track webhook delivery status

8. Suppression Management​

Automatic Suppression​

  • Bounce handling - Automatically suppress hard bounces
  • Spam complaints - Track and respect spam reports
  • Unsubscribes - Honor global unsubscribe requests

Manual Management​

  • Add to suppression list - Manually block specific addresses
  • Import suppression lists - Bulk import from CSV
  • Suppression reasons - Track why addresses are suppressed
  • Re-enable functionality - Remove addresses from suppression

Technical Architecture​

Technology Stack​

Backend​

  • Runtime: Node.js 20+ with TypeScript (ESM)
  • Framework: Express.js
  • Database: PostgreSQL 15+ with Prisma ORM
  • Cache/Queue: Redis 7+ with BullMQ
  • Email Server: Postfix + OpenDKIM
  • Monitoring: Prometheus metrics (in progress)

Frontend​

  • Framework: React 18+ with TypeScript
  • Build Tool: Vite
  • UI Library: shadcn/ui (Radix UI + Tailwind CSS)
  • State Management: TanStack Query (React Query)
  • Routing: React Router v6
  • Code Editor: Monaco Editor (VS Code editor)
  • Flow Builder: React Flow (xyflow)
  • Forms: React Hook Form
  • Charts: Recharts (coming soon)

Infrastructure​

  • Package Manager: pnpm workspaces
  • Containerization: Docker & Docker Compose
  • API Documentation: OpenAPI/Swagger (coming soon)
  • Testing: Vitest + React Testing Library (in progress)

Monorepo Structure​

postchi/
├── packages/
│   ├── api/          # REST API server
│   ├── worker/       # Background job processor
│   └── shared/       # Shared types, utilities, and Prisma schema
├── apps/
│   └── dashboard/    # React web dashboard
├── config/           # Configuration files (Nginx, Postfix, Supervisor)
├── docker/           # Dockerfiles
└── docs/             # Documentation

Email Flow Architecture​

  1. API Request → Client sends email via REST API
  2. Validation → Request validated against organization limits
  3. Queue → Job added to Redis queue (BullMQ)
  4. Worker → Background worker picks up job
  5. Processing → Email formatted, signed with DKIM
  6. SMTP → Sent to Postfix for delivery
  7. Delivery → Postfix delivers to recipient mail server
  8. Events → Delivery events tracked and webhooks triggered

Database Schema Highlights​

  • Organizations - Multi-tenant isolation
  • Users - Dashboard authentication and RBAC
  • Domains - Verified sending domains with DNS records
  • Messages - Complete email logs with status tracking
  • MessageEvents - Event timeline (sent, delivered, opened, etc.)
  • Templates - Versioned email templates
  • Contacts - Contact database with custom fields
  • Lists & Tags - Segmentation system
  • Flows - Automation workflows with versions
  • Webhooks - Event notification endpoints
  • SuppressionList - Bounce and complaint management
  • ApiKeys - Programmatic access tokens

User Interface Highlights​

Dashboard Design​

  • Modern, clean interface - Built with shadcn/ui component library
  • Dark mode ready - Professional dark theme support
  • Responsive - Works on desktop, tablet, and mobile
  • Accessible - ARIA labels and keyboard navigation
  • Fast - Optimized with React Query for instant updates

Key UI Features​

  • Real-time updates - Instant feedback on actions
  • Toast notifications - Non-intrusive success/error messages
  • Loading states - Skeleton screens and spinners
  • Empty states - Helpful guidance when no data exists
  • Confirmation dialogs - Prevent accidental deletions
  • Form validation - Inline validation with helpful error messages
  • Search & filtering - Find what you need quickly
  • Pagination - Handle large datasets efficiently

Competitive Advantages​

vs. SendGrid​

  • ✅ Complete control - Full control and transparency
  • ✅ Privacy focused - Keep your data private
  • ✅ Predictable costs - No hidden fees
  • ✅ Visual automation - More powerful flow builder
  • ✅ Integrated contacts - Built-in CRM features

vs. Mailgun​

  • ✅ Modern UI - Better user experience
  • ✅ Automation workflows - Marketing automation included
  • ✅ Flexible rate limits - Control your own rate limits
  • ✅ Template editor - Professional code editor built-in

vs. Mailchimp​

  • ✅ Transactional + Marketing - Both in one platform
  • ✅ API-first design - Better for developers
  • ✅ Enterprise ready - For compliance and privacy
  • ✅ Scalable contacts - Unlimited contacts

Possible Future Features​

High Priority​

Analytics & Reporting​

  • 📊 Advanced analytics dashboard - Deeper insights into email performance
  • 📈 Custom reports - Build and save custom report views
  • 📉 Funnel analysis - Track conversion through email journeys
  • 🎯 A/B testing - Test subject lines, content, send times
  • 📅 Scheduled reports - Automatic report delivery via email

Deliverability​

  • 🔍 Inbox placement testing - Test how emails land across providers
  • 📧 Deliverability monitoring - Real-time deliverability scores
  • 🛡️ Spam score checking - Pre-send spam analysis
  • 🌐 IP reputation tracking - Monitor sending IP reputation
  • 📋 Deliverability tips - AI-powered recommendations

Email Builder​

  • 🎨 Visual email builder - Drag-and-drop email design tool
  • 📱 Mobile preview - See emails on different devices
  • 🖼️ Image hosting - Built-in CDN for email images
  • 🎭 Dynamic content blocks - Show/hide content based on recipient data
  • 💾 Content blocks library - Reusable email components

Automation Enhancements​

  • ⏰ Advanced scheduling - Time zone aware sending
  • 🔁 Recurring campaigns - Schedule repeating emails
  • 🎯 Behavioral triggers - React to user actions
  • 🌳 Multi-path workflows - Complex branching logic
  • 🧪 Flow testing - Test automations before going live

Medium Priority​

Contact Management​

  • 🔄 Two-way sync - Sync with CRMs (Salesforce, HubSpot)
  • 📊 Contact scoring - Engagement-based lead scoring
  • 🏷️ Smart segments - Auto-update segments based on criteria
  • 📝 Contact activity timeline - Full engagement history
  • 🔍 Advanced search - Complex contact queries

Compliance & Privacy​

  • ⚖️ GDPR tools - Data export, deletion, consent tracking
  • 📜 CAN-SPAM compliance - Automatic compliance checking
  • 🔒 Data encryption - At-rest and in-transit encryption
  • 📋 Audit logs - Complete activity logging
  • 🌍 Regional compliance - Per-region email rules

Team Collaboration​

  • 💬 Comments on campaigns - Team discussion threads
  • 📝 Draft approval workflow - Review before sending
  • 👥 Team workspaces - Organize work by team/project
  • 📞 Notification preferences - Customize team alerts
  • 🎓 User training mode - In-app tutorials

API & Integrations​

  • 🔌 Zapier integration - Connect to 5000+ apps
  • 🪝 Webhook builder - Visual webhook configuration
  • 📚 API rate limit management - Per-key rate limits
  • 🔐 OAuth support - Third-party app integrations
  • 📖 GraphQL API - Modern API option

Nice to Have​

Advanced Features​

  • 🤖 AI writing assistant - Generate email copy
  • 🌐 Multi-language support - Internationalization
  • 📱 Mobile app - iOS and Android dashboard apps
  • 🎙️ Voice messages - Send voice notes via email
  • 🎥 Video messages - Embed and track video in emails
  • 📊 Custom dashboards - Build personalized views
  • 🔔 SMS integration - Multi-channel messaging
  • 📞 Phone number validation - Verify contact data
  • 🗺️ Geolocation tracking - See where emails are opened
  • 🎨 Brand kit - Store brand colors, fonts, logos

Enterprise Features​

  • 🏢 SSO integration - SAML, LDAP, OAuth
  • 📊 Multi-organization dashboard - Manage multiple orgs
  • 💳 Usage-based billing - Built-in billing system
  • 🎫 Support ticketing - Customer support system
  • 📈 SLA monitoring - Track uptime and performance
  • 🔐 Advanced security - 2FA, IP whitelisting, encryption
  • 🏗️ Infrastructure management - Multi-region deployment
  • 📦 Kubernetes support - Cloud-native deployment

Marketing Features​

  • 🎁 Loyalty programs - Points and rewards tracking
  • 🛒 E-commerce integration - Shopify, WooCommerce
  • 📅 Event management - Webinar and event emails
  • 🎟️ Coupon management - Generate and track coupons
  • 📰 Newsletter management - RSS to email, archives
  • 🔗 Link shortening - Built-in URL shortener
  • 📸 Social media integration - Share to social platforms

Current Limitations​

What's Not Yet Built​

  1. Click & Open Tracking - Event tracking is partially implemented
  2. Email Throttling - Per-organization sending limits need refinement
  3. Bounce Processing - Automatic bounce categorization in progress
  4. Webhook Retry Logic - Basic retry needs enhancement
  5. API Documentation - Swagger/OpenAPI docs in progress
  6. Test Coverage - Unit and integration tests needed
  7. Production Deployment - Docker/K8s deployment guides needed
  8. Monitoring - Prometheus metrics partially implemented

Known Issues​

  • Template preview - Live preview not yet functional
  • Export features - CSV export for logs/contacts pending
  • Bulk operations - Some bulk actions need UI improvements
  • Mobile responsiveness - Some pages need mobile optimization
  • Error handling - Some error messages could be more helpful

Deployment Options​

Current Setup​

  • Docker Compose - Single-server deployment (current)
  • Manual setup - Node.js + PostgreSQL + Redis + Postfix

Planned Support​

  • Docker Swarm - Multi-node clustering
  • Kubernetes - Cloud-native deployment
  • Helm charts - Easy K8s deployment
  • One-click deploy - DigitalOcean, Heroku, Railway
  • AWS/GCP/Azure - Cloud provider guides

Use Cases​

Transactional Emails​

  • Password reset emails
  • Order confirmations
  • Shipping notifications
  • Account verification
  • Payment receipts
  • System notifications

Marketing Emails​

  • Welcome series
  • Product announcements
  • Newsletter campaigns
  • Promotional offers
  • Event invitations
  • Re-engagement campaigns

Automation Workflows​

  • Drip campaigns
  • Onboarding sequences
  • Abandoned cart recovery
  • Win-back campaigns
  • Birthday/anniversary emails
  • Behavior-based messaging

Internal Communications​

  • Team notifications
  • Alert systems
  • Report delivery
  • Digest emails
  • Status updates

Target Users​

Developers​

  • Need transactional email for their apps
  • Want API-first approach
  • Need reliable infrastructure
  • Value modern technology

Small Businesses​

  • Need affordable email marketing
  • Want simple automation
  • Need reliable delivery
  • Need combined transactional + marketing

Agencies​

  • Manage multiple clients
  • Need white-label option
  • Want full control
  • Require compliance features

Enterprises​

  • Need enterprise deployment
  • Require data privacy
  • Want customization
  • Need high volume sending

Questions for Discussion​

Feature Priorities​

  1. What features would make this immediately useful for you?
  2. Which "nice to have" features would you actually use?
  3. Are there any critical features missing from this list?

Target Market​

  1. Who do you see as the primary users of this platform?
  2. What pricing model would work best for our target customers?
  3. How does this compare to other solutions you've used?

Technical Decisions​

  1. Is the tech stack appropriate for the goals?
  2. What deployment models should we prioritize?
  3. Any concerns about scalability or performance?

Go-to-Market​

  1. How would you position this vs. competitors?
  2. What's the most compelling selling point?
  3. What type of documentation/tutorials would be most helpful?

Development Roadmap​

  1. What should we build next?
  2. What can we skip or simplify?
  3. What would make this a "must-have" vs. "nice-to-have"?

Conclusion​

Postchi is shaping up to be a comprehensive email platform that combines the best of transactional email services (like SendGrid/Mailgun) with marketing automation features (like Mailchimp/ActiveCampaign).

Current Status: MVP with core features functional, ready for testing and feedback.

Next Steps:

  1. Complete click/open tracking
  2. Enhance webhook system
  3. Add comprehensive testing
  4. Create deployment guides
  5. Build API documentation
  6. Add more template starters
  7. Improve mobile responsiveness

Document Version: 1.0 Last Updated: January 2025 Created by: Postchi Team License: MIT