WebMail-BIMI-API

A high-performance Node.js DNS lookup service that provides comprehensive email security and domain validation capabilities. Built specifically for webmail applications with support for BIMI, SPF, DKIM, DMARC, and MX record queries.

• 🖥️ WebMail UI: github.com/Yukthi-Systems/WebMail-UI
• 💬 Discord: discord.gg/29zTxvque

🚀 Features

• BIMI Record Lookup - Brand Indicators for Message Identification
• SPF Record Query - Sender Policy Framework validation
• DKIM Record Lookup - DomainKeys Identified Mail verification
• DMARC Policy Check - Domain-based Message Authentication
• MX Record Resolution - Mail server discovery
• Domain Validation - Comprehensive validation of all DNS records

📋 Prerequisites

• Node.js >= 18.0.0
• npm >= 8.0.0

🛠️ Installation

1. Clone the repository

   git clone https://github.com/Yukthi-Systems/WebMail-BIMI-API
   cd WebMail-BIMI-API

2. Install dependencies

   npm install

3. Set up environment variables

   cp .env.example .env
   # Edit .env with your configuration

4. Build the project

   npm run build

🏃 Quick Start

Development Mode:

npm run dev

Production Mode:

npm start

The API will be available at http://localhost:3001

📡 API Endpoints

Base URL

http://localhost:3001/api/dns

Health Check

GET /health

Returns server health status and uptime information.

Individual DNS Lookups

BIMI Record

GET /api/dns/bimi?domain=example.com

Retrieves BIMI (Brand Indicators for Message Identification) records.

SPF Record

GET /api/dns/spf?domain=example.com

Queries SPF (Sender Policy Framework) records for email authentication.

DKIM Record

GET /api/dns/dkim?domain=example.com&selector=mailsvc

Looks up DKIM public keys. The selector parameter is optional and defaults to mailsvc.

DMARC Record

GET /api/dns/dmarc?domain=example.com

Retrieves DMARC (Domain-based Message Authentication) policy records.

MX Record

GET /api/dns/mx?domain=example.com

Resolves MX (Mail Exchange) records sorted by priority.

Comprehensive Domain Validation

Validate Domain

GET /api/dns/validate?domain=example.com&selector=mailsvc

Performs comprehensive validation of all DNS records in a single request. Returns:

• MX, SPF, DKIM, DMARC, and BIMI record status
• Validation score (0-100%)
• Detailed results for each record type
• Summary of passed/failed checks

🏢 Company Branding & Assets

The API supports multi-tenant branding based on a unique slug. This allows serving specific logos and backgrounds for different companies/instances.

Fetch Company Configuration

GET /api/dns/company-config/:slug?

Returns the full branding configuration (slug, domains, asset mappings, theme) for a given slug or domain.

Fetch Branding Assets

GET /api/dns/logo-image/:slug?
GET /api/dns/bg-image/:slug?

Serves the specific logo or background image for a company.

• Slug: Path parameter (e.g., /logo-image/example)
• Domain Fallback: Query parameter (e.g., /logo-image?domain=example.com)
• Dark Mode: Supports ?mode=dark query parameter.

Update Company & Assets (Unified API)

POST /api/dns/update-company

Unified endpoint to update company details and upload assets in a single request.

Form Data Fields:

• slug (Required): Unique identifier for the company.
• name (Optional): Display name.
• domains (Optional): Comma-separated list of domains.
• logo: Image file.
• background: Image file.
• logoDark: Image file for dark mode.
• backgroundDark: Image file for dark mode.

📝 Response Format

All endpoints return responses in the following format:

{
  "success": true,
  "data": {
    // Response data specific to the endpoint
  },
  "timestamp": 1703123456789
}

Error Response

{
  "success": false,
  "error": "DNS query failed",
  "message": "Domain not found",
  "timestamp": 1703123456789
}

🔧 Configuration

Environment Variables

Create a .env file with the following variables:

# Server Configuration
PORT=3001
NODE_ENV=development

# CORS Configuration
CORS_ORIGIN=http://localhost:3000,http://localhost:5173

# Branding & Assets Configuration
DOMAIN_IMAGES_PATH=/data/images
COMPANIES_CONFIG_PATH=/data/config/companies.json

Persistence (Docker)

To ensure your configurations and images survive container restarts, map a volume to /data:

services:
  dns-lookup-api:
    # ...
    volumes:
      - ./data:/data

DNS Configuration

The service uses reliable public DNS servers:

• Google DNS: 8.8.8.8, 8.8.4.4
• Cloudflare DNS: 1.1.1.1

📊 Rate Limiting

• Default Limit: 100 requests per minute per IP address
• Response: HTTP 429 when limit exceeded
• Reset: Automatically resets every minute

📁 Project Structure

src/
├── controller/          # Request handlers
│   └── dns.ts          # DNS lookup controllers
├── middleware/         # Express middleware
│   ├── rateLimiter.ts  # Rate limiting logic
│   └── validations.ts  # Input validation
├── routes/            # API route definitions
│   └── dns.ts         # DNS routes
├── types/             # TypeScript type definitions
│   └── dns.ts         # DNS-related types
├── utils/             # Utility functions
│   └── logger.ts      # File logging system
├── app.ts             # Express app configuration
└── server.ts          # Server entry point

🛡️ Security Features

• Helmet.js: Security headers
• CORS: Cross-origin resource sharing protection
• Input Validation: Domain format validation
• Rate Limiting: Request throttling per IP
• Error Sanitization: No sensitive data in error responses

📈 Usage Examples

cURL Examples

Basic SPF lookup:

curl "http://localhost:3001/api/dns/spf?domain=gmail.com"

DKIM with custom selector:

curl "http://localhost:3001/api/dns/dkim?domain=gmail.com&selector=20230601"

Comprehensive domain validation:

curl "http://localhost:3001/api/dns/validate?domain=example.com"

🔍 DNS Record Details

DKIM Selectors

• Default: mailsvc (configurable)
• Common selectors: default, selector1, google, microsoft
• Format: [selector]._domainkey.[domain]

Record Locations

• SPF: TXT record at domain root
• DMARC: TXT record at _dmarc.[domain]
• DKIM: TXT record at [selector]._domainkey.[domain]
• BIMI: TXT record at default._bimi.[domain]
• MX: MX record at domain root

🚨 Error Handling

The API handles various DNS errors gracefully:

• ENOTFOUND: Domain not found
• ENODATA: No DNS records found
• Timeout: DNS query timeout (5 second limit)
• Invalid Format: Malformed domain names

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-feature)
3. Commit your changes (git commit -am 'Add new feature')
4. Push to the branch (git push origin feature/new-feature)
5. Create a Pull Request

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.