The modern email automation platform for managing and streamlining your email operations.
IN PROGRESS
COMING SOON
IN PROGRESSWe're actively working on comprehensive development documentation to help you get started with ColdJot. In the meantime, please refer to the Getting Started section below. If you have any questions, feel free to open an issue or join our community!
- What is ColdJot?
- Why ColdJot?
- Our Mission
- Features
- Open Source Commitment
- Development Status
- Screenshot
- Tech Stack
- Getting Started
- Setting Up Email Reply Notifications
- Contributing
- Issues
- Pull Request
- License
ColdJot is a powerful email automation platform designed to help businesses manage and streamline their email operations. With a focus on productivity and efficiency, ColdJot provides advanced email management capabilities, real-time processing, and a modern web interface.
Most email automation tools today are either overly complex, expensive, or lack modern features. ColdJot is different:
✅ Powerful Automation – Streamline your email workflows with advanced automation capabilities.
🔒 Efficient Processing – Queue-based operations ensure reliable delivery and performance.
⚙️ Modern Interface – Clean, intuitive UI that makes email management a breeze.
📊 Comprehensive Analytics – Track and analyze your email performance with detailed insights.
🎨 Customizable Templates – Create and manage email templates that reflect your brand.
🤖 AI Features COMING SOON – Leverage artificial intelligence to enhance email personalization and optimize send times.
We believe email automation should be:
- Efficient – Save time and resources with streamlined workflows.
- Powerful – Provide advanced capabilities for complex email operations.
- User-Friendly – Intuitive interface that doesn't require technical expertise.
- Reliable – Ensure consistent delivery and performance.
Create and manage sophisticated email sequences with ease. Schedule, automate, and track your email campaigns effortlessly.
- Multi-step sequence automation
- Flexible timing and scheduling
- Conditional logic for personalized follow-ups
- A/B testing capabilities
IN PROGRESS
Get detailed insights into your email campaigns with comprehensive analytics:
- Open and click tracking
- Response rate monitoring
- Sequence performance metrics
- Engagement analytics
- Advanced reporting
COMING SOON
Import, organize, and manage your contacts efficiently:
- Contact list segmentation
- Import functionality
- Activity history tracking
- Advanced filtering and tagging
IN PROGRESS
Create and save reusable email templates to maintain consistency and save time:
- Rich text editor
- Make changes in one location, and it will automatically reflect everywhere
- Dynamic content personalization
COMING SOON
Manage all your email accounts from a single platform:
- Connect unlimited email accounts
- Centralized management interface
- Separate sending quotas for each mailbox
- Mailbox-specific settings and configurations
- Distribute campaigns across multiple mailboxes for higher deliverability
- Unified inbox
IN PROGRESS
Connect and manage multiple Gmail mailboxes:
- Send emails from your preferred Gmail account
- Reply tracking
- Quota management
- Automatic rate limiting to respect Gmail's sending limits
- OAuth-based secure authentication
- Advanced deliverability features
COMING SOON
Visualize your email sequence timeline and monitor outgoing communications in real-time:
- Visual sequence builder
- Drag-and-drop interface
IN PROGRESS - Real-time status updates
- Campaign calendar view
COMING SOON
- Secure authentication with Google OAuth
- Privacy-focused design
- Data protection measures
- Role-based access control
IN PROGRESS
ColdJot is and will always remain open source. We believe in the power of community-driven software and are committed to maintaining ColdJot as a free and open platform.
- Forever Free: The core ColdJot platform will always be available as open source software
- No Vendor Lock-in: You own your data and can self-host without restrictions
- Transparent Development: Our development process is open and community-driven
- AGPLv3 License: Freedom to use, modify, and distribute the software while ensuring contributions remain open source
While we may offer premium hosted services in the future, the core platform will remain open source, ensuring you always have the freedom to run ColdJot on your own terms.
🚧 ColdJot is currently under active development 🚧
As an evolving platform, ColdJot is in its early stages and may contain bugs or incomplete features. We're working diligently to improve it every day, but we need your help to make it even better!
We believe in the power of community-driven development. If you're a developer, designer, or email enthusiast:
- Try it out – Test the platform and provide feedback
- Report bugs – Help us identify and fix issues
- Suggest features – Share your ideas for improvements
- Contribute code – Join our growing community of contributors
Your input is invaluable in shaping ColdJot into an awesome platform that truly serves the needs of its users. Together, we can build something remarkable!
ColdJot is built with modern and reliable technologies:
- Next.js – framework
- TypeScript – language
- Tailwind – CSS
- PostgreSQL – database
- Redis – caching & queues
- BullMQ – job processing
- Auth.js – authentication
- Turborepo – monorepo
- Prisma – ORM
Required Versions:
- Node.js >= 20.0.0
- npm >= 8.0.0 (or yarn)
- Docker >= 20.10.0 (for local services)
- PostgreSQL >= 14.0.0 (if not using Docker)
- Redis >= 6.0.0 (if not using Docker)
Before running the application, you'll need to set up several services and environment variables:
-
Setup Local Services with Docker
-
Google OAuth Setup
- Go to Google Cloud Console
- Create a new project
- Add the following APIs in your Google Cloud Project:
- Create two OAuth 2.0 credentials (Web application type):
- One for login with the basic scopes for user authentication.
- Another for mailboxes with the required scopes for accessing mailbox data.
- Add authorized redirect URIs:
- Login:
http://localhost:3000/api/auth/callback/google
- Mailboxes:
http://localhost:3000/api/mailboxes/gmail/callback
- Login:
[!WARNING] The redirect URIs must match exactly what you configure in the Google Cloud Console, including the protocol (http/https), domain, and path.
- Copy the example env files:
# Copy example env files
cp apps/web/env/.env.example apps/web/env/.env.development
cp apps/mailops/env/.env.example apps/mailops/env/.env.development
cp packages/database/env/.env.example packages/database/env/.env.development- Configure the environment variables in each
.envor.env.developmentfile:
# General
LOG_LEVEL=debug # Log level
APP_ENV=development # App environment
NODE_ENV=development # Node environment
NEXT_PUBLIC_APP_ENV=development # Next public app environment
# URLs
NEXTAUTH_URL=http://localhost:3000 # Next auth url
NEXT_PUBLIC_APP_URL=http://localhost:3000 # Next public app url
NEXT_PUBLIC_MAILOPS_API_URL="http://localhost:3001/api" # Next public mailops api url
# Secrets
NEXTAUTH_SECRET=your_random_secret_key # Use `openssl rand -hex 32` to generate
ENCRYPTION_KEY= # Encryption key
AUTH_TRUST_HOST= # Auth trust host
# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/coldjot_dev
# Google OAuth2 (Required for Authentication)
GOOGLE_CLIENT_ID= # Google client id
GOOGLE_CLIENT_SECRET= # Google client secret
GOOGLE_REDIRECT_URI=http://localhost:3001/api/auth/callback/google
# Google Mailbox OAuth2 (Required for Email Integration)
GOOGLE_CLIENT_ID_EMAIL= # Google client id for email
GOOGLE_CLIENT_SECRET_EMAIL= # Google client secret for email
GOOGLE_REDIRECT_URI_EMAIL=http://localhost:3000/api/mailboxes/gmail/callback# General Configuration
LOG_LEVEL=debug # debug, info, warn, error
APP_ENV=development # development, production
NODE_ENV=development # development, production
PORT=3001 # Port for the mailops api
BYPASS_BUSINESS_HOURS=false # Bypass business hours check in code
# URLs
WEB_APP_URL=http://localhost:3000 # URL for the web app
MAILOPS_API_URL=http://localhost:3001 # URL for the mailops api
TRACK_API_URL=https://coldjot.loca.lt # URL for the tracking in the email
# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/coldjot_dev
# Redis Configuration
REDIS_HOST=localhost # Redis host
REDIS_PORT=6379 # Redis port
REDIS_PASSWORD= # Redis password (if any)
# Queue Configuration
QUEUE_PREFIX=coldjot # Prefix for the queue
# Google Mailbox OAuth2
GOOGLE_CLIENT_ID_EMAIL= # Google client ID for email
GOOGLE_CLIENT_SECRET_EMAIL= # Google client secret for email
GOOGLE_REDIRECT_URI_EMAIL=http://localhost:3000/api/mailboxes/gmail/callback
# Optional: PubSub Configuration (for email reply tracking)
GOOGLE_CLOUD_PROJECT= # Google Cloud Project ID
PUBSUB_SUBSCRIPTION_NAME= # PubSub subscription name
PUBSUB_TOPIC_NAME= # PubSub topic name
PUBSUB_AUDIENCE= # PubSub audience URL for webhooks
# Optional: Google Service Account (for PubSub)
GOOGLE_SERVICE_ACCOUNT_EMAIL= # Google service account email
GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY= # Google service account private keyImportant
- Never commit your
.envfiles to version control - Use strong, unique values for all secret keys
- Keep your Google OAuth credentials secure
- In production, use different values for all credentials and URLs
- Create and migrate the database:
# Create a new PostgreSQL database
database_name = coldjot_dev
# Run database migrations
cd packages/database
npm run db:generate
npm run db:migrate- Optional: View and manage your data
npm run db:studio- Start the required services:
# Start Redis and PostgreSQL if not running
docker-compose up -d- Run the development server:
npm run dev- Open http://localhost:3000 with your browser to see the result.
The development server includes:
- Web application (Next.js) on port 3000
- Mail operations service on port 3001
- Background job processing
To receive real-time notifications when users reply to emails sent through ColdJot, you can set up Google Cloud PubSub. This section guides you through the process.
- Go to the Google Cloud Console Credentials page
- Select your project
- Click "Create Credentials" and select "Service Account"
- Give your service account a name (e.g., "coldjot-pubsub")
- Assign the following roles:
- Pub/Sub Subscriber
- Pub/Sub Viewer
- Pub/Sub Publisher
- Click "Done" to create the service account
- Find your new service account in the list and click on it
- Go to the "Keys" tab and click "Add Key" → "Create new key"
- Select JSON format and click "Create"
- Save the downloaded JSON file securely
- In the Google Cloud Console, navigate to Pub/Sub Topics
- Click "Create Topic"
- Name your topic (e.g., "coldjot-email-replies")
- Click "Create"
- On the topic details page, click "Create Subscription"
- Name your subscription (e.g., "coldjot-email-replies-sub")
- Set the delivery type to "Push"
- For the endpoint URL, you'll need a public URL that points to your local development environment (we'll set this up in the next step)
- Under "Authentication", select "Enable authentication"
- Choose the service account you created earlier
- Click "Create"
Since your development environment runs locally, you need a way to receive webhook notifications from Google Cloud. ngrok provides a secure tunnel to your localhost.
- Sign up for a free ngrok account at ngrok.com
- Download and install ngrok
- Authenticate ngrok with your auth token:
ngrok config add-authtoken YOUR_AUTH_TOKEN
- Start ngrok to create a tunnel to your mailops service:
ngrok http 3001
- ngrok will provide you with a public URL (e.g.,
https://abc123.ngrok.io) - Copy this URL and update your PubSub subscription endpoint URL to:
https://YOUR_NGROK_URL/api/webhooks/pubsub - Also update your
.envfile with this URL:PUBSUB_AUDIENCE=https://YOUR_NGROK_URL/api/webhooks/pubsub
- Go back to your PubSub topic in the Google Cloud Console
- Click on the "Permissions" tab
- Click "Add Principal"
- Add
gmail-api-push@system.gserviceaccount.comas a principal - Assign the "Pub/Sub Publisher" role
- Click "Save"
Open your apps/mailops/env/.env.development file and add the following variables:
# PubSub Configuration
GOOGLE_CLOUD_PROJECT=your-project-id # Your Google Cloud Project ID
PUBSUB_SUBSCRIPTION_NAME=coldjot-email-replies-sub # Your subscription name
PUBSUB_TOPIC_NAME=coldjot-email-replies # Your topic name
PUBSUB_AUDIENCE=https://YOUR_NGROK_URL/api/webhooks/pubsub # Your ngrok URL + path
# Google Service Account (from the downloaded JSON key file)
GOOGLE_SERVICE_ACCOUNT_EMAIL=your-service-account@your-project.iam.gserviceaccount.com
GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour private key content\n-----END PRIVATE KEY-----\n"[!NOTE] For the private key, make sure to:
- Include the entire key including the BEGIN and END lines
- Replace newlines with
\ncharacters- Enclose the entire key in double quotes
After configuring everything, restart your development server to apply the changes:
npm run dev- Webhook Verification Errors: Ensure your ngrok URL is correctly set in both the PubSub subscription and your environment variables.
- Authentication Issues: Verify that your service account has the correct permissions and that the key is properly formatted in your
.envfile. - No Notifications: Check that the Gmail API is properly configured to use your PubSub topic and that the
gmail-api-push@system.gserviceaccount.comaccount has publisher permissions. - ngrok Connection Issues: Make sure ngrok is running and that you're using the current URL (ngrok URLs change each time you restart unless you have a paid plan).
We love our contributors! Here's how you can contribute:
- Open an issue if you believe you've encountered a bug.
- Make a pull request to add new features/make quality-of-life improvements/fix bugs.
If you spot a problem with the docs, search if an issue already exists. If a related issue doesn't exist, you can open a new issue using a relevant issue form.
Scan through our existing issues to find one that interests you. You can narrow down the search using labels as filters. As a general rule, we don't assign issues to anyone. If you find an issue to work on, you are welcome to open a PR with a fix.
When you're finished with the changes, create a pull request, also known as a PR.
- Fill the "Ready for review" template so that we can review your PR. This template helps reviewers understand your changes as well as the purpose of your pull request.
- Don't forget to link PR to issue if you are solving one.
- Enable the checkbox to allow maintainer edits so the branch can be updated for a merge. Once you submit your PR, a reviewer will review your proposal. We may ask questions or request additional information.
- We may ask for changes to be made before a PR can be merged, either using suggested changes or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork and then commit them to your branch.
- As you update your PR and apply changes, mark each conversation as resolved.
- If you run into any merge issues, check out this git tutorial to help you resolve merge conflicts and other issues.
ColdJot is open-source under the GNU Affero General Public License Version 3 (AGPLv3) or any later version. You can find it here.
🤍 ColdJot – Email Automation, Reimagined.