A Django-based system that fetches emails from IMAP servers and provides access through a web interface and REST API. The system is designed to be simple yet powerful, with features like email threading, folder management, and flexible sync options.
- IMAP server integration with SSL/TLS support
- Email threading support
- Flexible sync options (all messages, last N messages, time-based)
- Folder management with exclusion rules
- Web interface for email viewing and management
- REST API compatible with Gmail API structure
- Token-based authentication
- UTF-8 encoding support
- Full email content storage (headers, body, attachments)
- Thread detection and grouping
- Folder-based organization
- Responsive design using Bootstrap
- Email list with threading support
- Advanced search and filtering
- IMAP server management
- User authentication
- RESTful endpoints
- Token authentication
- Search and filtering capabilities
- Thread-aware email retrieval
- Folder management
- Docker and Docker Compose
- Git
- Clone the repository:
git clone https://github.com/PiotrEsse/SimpleImap2Api.git
cd SimpleImap2Api- Create a
.envfile:
# Django settings
DJANGO_SECRET_KEY=your-secret-key
DJANGO_DEBUG=False
ALLOWED_HOSTS=localhost,127.0.0.1
# Database settings
DB_NAME=simple_imap2api
DB_USER=dbuser
DB_PASSWORD=dbpassword
DB_HOST=db
DB_PORT=5432- Build and run with Docker Compose:
docker-compose up -d- Create a superuser:
docker-compose exec web python manage.py createsuperuser- Clone the repository:
git clone https://github.com/yourusername/SimpleImap2Api.git
cd SimpleImap2Api- Create a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- Install dependencies:
pip install -r requirements.txt- Set up the database:
python manage.py migrate- Create a superuser:
python manage.py createsuperuser- Run the development server:
python manage.py runserver- Log in to the admin interface at
/admin - Add a new IMAP server configuration:
- Server name (for identification)
- Host and port
- Username and password
- SSL/TLS settings
- Sync options:
- All messages
- Last N messages
- Messages from last N days/weeks/months
- Folder settings:
- Specific folders to sync
- Exclude trash option
Use the web interface:
- Go to IMAP Servers page
- Click "Sync" button for the desired server
Set up a cron job to run:
# In Docker:
docker-compose exec web python manage.py sync_emails
# Manual installation:
python manage.py sync_emailsOptional parameters:
--user <id>: Sync specific user's servers--days <number>: Override sync period
- Obtain an authentication token:
curl -X POST http://localhost:8000/api-token-auth/ \
-H "Content-Type: application/json" \
-d '{"username": "your_username", "password": "your_password"}'- Use the token in requests:
curl -H "Authorization: Token your_token_here" \
http://localhost:8000/api/emails/GET /api/emails/: List emailsGET /api/emails/{id}/: Get email detailsGET /api/emails/{id}/thread/: Get email threadGET /api/emails/threads/: List email threads
Query parameters:
q: Search termfolder: Filter by folderdate_from,date_to: Date rangethread: Show threaded view
GET /api/imap-servers/: List serversPOST /api/imap-servers/: Add serverPUT /api/imap-servers/{id}/: Update serverPOST /api/imap-servers/{id}/sync/: Trigger sync
version: '3.8'
services:
db:
image: postgres:13
volumes:
- postgres_data:/var/lib/postgresql/data
environment:
- POSTGRES_DB=${DB_NAME}
- POSTGRES_USER=${DB_USER}
- POSTGRES_PASSWORD=${DB_PASSWORD}
web:
build: .
command: gunicorn simple_imap2api.wsgi:application --bind 0.0.0.0:8000
volumes:
- .:/app
- static_volume:/app/staticfiles
- media_volume:/app/media
expose:
- 8000
environment:
- DJANGO_SECRET_KEY=${DJANGO_SECRET_KEY}
- DJANGO_DEBUG=${DJANGO_DEBUG}
- ALLOWED_HOSTS=${ALLOWED_HOSTS}
- DB_NAME=${DB_NAME}
- DB_USER=${DB_USER}
- DB_PASSWORD=${DB_PASSWORD}
- DB_HOST=${DB_HOST}
- DB_PORT=${DB_PORT}
depends_on:
- db
nginx:
image: nginx:1.21
volumes:
- static_volume:/app/staticfiles
- media_volume:/app/media
- ./nginx.conf:/etc/nginx/conf.d/default.conf
ports:
- "80:80"
depends_on:
- web
volumes:
postgres_data:
static_volume:
media_volume:FROM python:3.12-slim
ENV PYTHONUNBUFFERED=1
ENV PYTHONDONTWRITEBYTECODE=1
WORKDIR /app
RUN apt-get update && apt-get install -y \
build-essential \
libpq-dev \
&& rm -rf /var/lib/apt/lists/*
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
RUN python manage.py collectstatic --noinput
EXPOSE 8000
CMD ["gunicorn", "simple_imap2api.wsgi:application", "--bind", "0.0.0.0:8000"]- Set up environment variables in
.env - Build and start containers:
docker-compose -f docker-compose.prod.yml up -d- Run migrations:
docker-compose exec web python manage.py migrate- Create superuser:
docker-compose exec web python manage.py createsuperuser- Set up cron job for email syncing:
docker-compose exec web python manage.py sync_emails- Use strong passwords
- Enable SSL/TLS for IMAP connections
- Keep Django secret key secure
- Use HTTPS in production
- Regularly update dependencies
- Monitor server logs
- Back up database regularly
-
Connection errors:
- Check IMAP server credentials
- Verify SSL/TLS settings
- Check firewall rules
-
Sync issues:
- Check folder permissions
- Verify folder names
- Check server timeout settings
-
Threading issues:
- Verify message IDs
- Check reference headers
- Validate email format
Access logs in Docker:
docker-compose logs webAccess Django logs:
tail -f logs/debug.log- Fork the repository
- Create a feature branch
- Make changes
- Submit pull request
MIT License - see LICENSE file for details