### Docker Compose Setup for CloakMail

Source: https://github.com/dreamshive/cloakmail/blob/main/README.md

This snippet demonstrates how to set up and run CloakMail using Docker Compose. It involves downloading the docker-compose.yml file, setting the domain environment variable, and starting the services. This is the primary method for deploying CloakMail on your own infrastructure.

```bash
curl -fsSL https://raw.githubusercontent.com/DreamsHive/cloakmail/main/docker-compose.yml -o docker-compose.yml

export DOMAIN=yourdomain.com

docker compose up -d
```

--------------------------------

### Docker Compose Setup for CloakMail

Source: https://context7.com/dreamshive/cloakmail/llms.txt

This Docker Compose configuration deploys the complete CloakMail stack, including the server, web UI, and Redis. It sets up persistent volumes for Redis data and defines environment variables for each service. The deployment can be initiated with a single command.

```yaml
services:
  server:
    image: ghcr.io/dreamshive/cloakmail-server:latest
    ports:
      - "25:25"
      - "3000:3000"
    environment:
      - REDIS_URL=redis://redis:6379
      - SMTP_PORT=25
      - API_PORT=3000
      - EMAIL_TTL_SECONDS=86400
      - DOMAIN=yourdomain.com
    depends_on:
      - redis
    restart: unless-stopped

  web:
    image: ghcr.io/dreamshive/cloakmail-web:latest
    ports:
      - "5173:5173"
    environment:
      - PUBLIC_API_URL=http://server:3000
      - PUBLIC_APP_NAME=CloakMail
      - PUBLIC_EMAIL_DOMAIN=yourdomain.com
      - PORT=5173
    depends_on:
      - server
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    restart: unless-stopped

volumes:
  redis_data:
```

```bash
# Quick start deployment
export DOMAIN=yourdomain.com
docker compose up -d

# Check service status
docker compose ps
docker compose logs -f server
```

--------------------------------

### GET /api/inbox/{address}

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Fetch all emails from a specific inbox address with pagination support.

```APIDOC
## GET /api/inbox/{address}

### Description
Retrieves a paginated list of emails associated with a specific email address.

### Method
GET

### Endpoint
/api/inbox/{address}

### Parameters
#### Path Parameters
- **address** (string) - Required - The full email address to fetch.

#### Query Parameters
- **page** (number) - Optional - Page number for pagination.
- **limit** (number) - Optional - Number of items per page.

### Request Example
GET /api/inbox/swift.falcon42@yourdomain.com?page=1&limit=20

### Response
#### Success Response (200)
- **emails** (array) - List of email objects.
- **pagination** (object) - Pagination metadata.

#### Response Example
{
  "emails": [{"id": "a1b2c3", "subject": "Hello", "from": "sender@test.com"}],
  "pagination": {"totalEmails": 1, "page": 1}
}
```

--------------------------------

### GET /api/health

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Returns the current health status of the service components.

```APIDOC
## GET /api/health

### Description
Returns the current health status of all service components including SMTP server, Redis connection, and process uptime.

### Method
GET

### Endpoint
/api/health

### Response
#### Success Response (200)
- **status** (string) - Current status (e.g., "ok").
- **smtp** (boolean) - SMTP server status.
- **redis** (boolean) - Redis connection status.
- **uptime** (number) - Process uptime in seconds.
```

--------------------------------

### GET /api/inbox/:email

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Retrieves all emails for a specific email address with support for pagination.

```APIDOC
## GET /api/inbox/:email

### Description
Fetches all emails received at a specific email address with pagination support. Returns an array of email objects sorted by received time.

### Method
GET

### Endpoint
/api/inbox/:email

### Parameters
#### Path Parameters
- **email** (string) - Required - The full email address to retrieve the inbox for.

#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve (default: 1).
- **limit** (integer) - Optional - The number of emails per page (default: 10).

### Response
#### Success Response (200)
- **emails** (array) - List of email objects.
- **pagination** (object) - Metadata including total count and page information.

#### Response Example
{
  "emails": [
    {
      "id": "a1b2c3d4e5f6g7h8i9j0",
      "to": "user@domain.com",
      "from": "sender@example.com",
      "subject": "Welcome",
      "receivedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalEmails": 1
  }
}
```

--------------------------------

### GET /api/email/:id

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Retrieves the full content of a specific email by its unique ID.

```APIDOC
## GET /api/email/:id

### Description
Fetches a specific email by its unique identifier. Returns the complete email object including headers, text content, and HTML content.

### Method
GET

### Endpoint
/api/email/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the email.

### Response
#### Success Response (200)
- **id** (string) - Email ID.
- **text** (string) - Plain text content.
- **html** (string) - HTML content.

#### Error Response (404)
- **error** (string) - "Email not found"
```

--------------------------------

### SMTP Server and Spam Filtering

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Initializes the SMTP server and demonstrates the spam filtering logic. It highlights the rejection of emails containing executable attachments.

```typescript
import { startSMTP, isSMTPRunning } from './smtp';
import { isSpam } from './spam';

const server = startSMTP(25);
const running = isSMTPRunning();
const spamResult = await isSpam(parsedEmail);
```

--------------------------------

### Configure CloakMail Environment Variables

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Defines the configuration settings for the CloakMail server, including ports, Redis connection strings, and email expiration policies.

```bash
SMTP_PORT=25
API_PORT=3000
REDIS_URL=redis://localhost:6379
EMAIL_TTL_SECONDS=86400
DOMAIN=yourdomain.com
MAX_EMAIL_SIZE_MB=10
```

--------------------------------

### Manage Redis Email Storage

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Demonstrates how to store, retrieve, and delete emails using the Redis storage module. It includes pagination support for inbox retrieval and a health check utility.

```typescript
import { storeEmail, getInbox, getEmail, deleteInbox, deleteEmail, isRedisHealthy } from './store';
import type { InboundEmail, StoredEmail, InboxResponse } from './types';

const email: InboundEmail = {
  to: 'swift.falcon42@yourdomain.com',
  from: 'sender@example.com',
  subject: 'Test Email',
  text: 'Plain text content',
  html: '<p>HTML content</p>',
  headers: { 'content-type': 'text/html' }
};
const emailId = await storeEmail(email);
const inbox: InboxResponse = await getInbox('swift.falcon42@yourdomain.com', 1, 10);
const stored: StoredEmail | null = await getEmail('a1b2c3d4e5f6g7h8i9j0');
const { deleted: count } = await deleteInbox('swift.falcon42@yourdomain.com');
const { deleted: success } = await deleteEmail('a1b2c3d4e5f6g7h8i9j0');
const healthy = await isRedisHealthy();
```

--------------------------------

### TypeScript API Client for Web Operations

Source: https://context7.com/dreamshive/cloakmail/llms.txt

This TypeScript code demonstrates how to use the @cloakmail/web package to interact with the CloakMail API. It includes functions for fetching and deleting emails and inboxes, as well as creating a server-side API client. Dependencies include openapi-fetch and generated types from the OpenAPI specification.

```typescript
import { fetchInbox, fetchEmail, deleteInbox, deleteEmail, createApiClient } from '@cloakmail/web';

// Fetch all emails from an inbox with pagination
const inbox = await fetchInbox('swift.falcon42@yourdomain.com', 1, 20);
console.log(`Found ${inbox.pagination.totalEmails} emails`);
for (const email of inbox.emails) {
  console.log(`${email.subject} from ${email.from}`);
}

// Fetch a specific email by ID
const email = await fetchEmail('a1b2c3d4e5f6g7h8i9j0');
console.log(email.html); // Render HTML content

// Delete all emails in an inbox
const result = await deleteInbox('swift.falcon42@yourdomain.com');
console.log(`Deleted ${result.deleted} emails`);

// Delete a single email
const deleted = await deleteEmail('a1b2c3d4e5f6g7h8i9j0');
console.log(deleted.deleted ? 'Email removed' : 'Email not found');

// Create custom client with server-side fetch
import { createApiClient } from '@cloakmail/web';
const serverClient = createApiClient(fetch);
const { data, error } = await serverClient.GET('/api/inbox/{address}', {
  params: { path: { address: 'test@yourdomain.com' } }
});
```

--------------------------------

### Pulling CloakMail Docker Images

Source: https://github.com/dreamshive/cloakmail/blob/main/README.md

This snippet shows how to pull the individual Docker images for the CloakMail server and web UI directly from GitHub Container Registry. This is an alternative to using docker-compose for deployment.

```bash
docker pull ghcr.io/dreamshive/cloakmail-server:latest
docker pull ghcr.io/dreamshive/cloakmail-web:latest
```

--------------------------------

### SMTP Server

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Receives incoming emails, applies spam filtering, and stores valid emails in Redis. Emails with executable attachments are automatically rejected.

```APIDOC
## SMTP Server

### Description
Receives incoming emails, parses them using mailparser, applies spam filtering, and stores valid emails in Redis. Emails with executable attachments are automatically rejected.

### Functions
- `startSMTP(port)`: Starts the SMTP server on the specified port.
- `isSMTPRunning()`: Checks if the SMTP server is running.

### Spam Filtering
Rejects emails with executable attachments. Blocked extensions include: `.exe`, `.bat`, `.cmd`, `.scr`, `.pif`, `.com`, `.vbs`, `.js`, `.wsh`, `.ps1`.

### Request Example (startSMTP)
```typescript
import { startSMTP } from './smtp';

const server = startSMTP(25); // Starts server on port 25
```

### Request Example (isSMTPRunning)
```typescript
import { isSMTPRunning } from './smtp';

const running = isSMTPRunning(); // true
```

### Request Example (isSpam)
```typescript
import { isSpam } from './spam';

// Assuming parsedEmail is the result of mailparser
const spamResult = await isSpam(parsedEmail);
// Returns: { isSpam: false, reason: null } or { isSpam: true, reason: "executable attachment detected" }
```
```

--------------------------------

### Retrieve Single Email by ID

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Fetches the full content of a specific email using its unique identifier. Returns a 404 status if the email has expired or does not exist.

```bash
curl -X GET "http://localhost:3000/api/email/a1b2c3d4e5f6g7h8i9j0"
```

--------------------------------

### Define Core Data Types

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Provides the TypeScript interfaces for email objects, pagination metadata, and spam detection results used across the CloakMail system.

```typescript
interface InboundEmail {
  to: string;
  from: string;
  subject: string;
  text: string;
  html: string;
  headers: Record<string, string>;
}

interface StoredEmail extends InboundEmail {
  id: string;
  receivedAt: string;
}

interface PaginationInfo {
  page: number;
  limit: number;
  totalEmails: number;
  totalPages: number;
  hasMore: boolean;
}

interface InboxResponse {
  emails: StoredEmail[];
  pagination: PaginationInfo;
}

interface SpamResult {
  isSpam: boolean;
  reason: string | null;
}
```

--------------------------------

### TypeScript Types

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Core data type definitions for email objects, pagination, and API responses used throughout the application.

```APIDOC
## TypeScript Types

### Description
Defines the core data structures used for emails, pagination, and API responses within the CloakMail application.

### Interfaces

#### `InboundEmail`
Represents an incoming email from the SMTP server.
```typescript
interface InboundEmail {
  to: string;
  from: string;
  subject: string;
  text: string;
  html: string;
  headers: Record<string, string>;
}
```

#### `StoredEmail`
Represents an email stored in Redis, including metadata.
```typescript
interface StoredEmail extends InboundEmail {
  id: string;           // 20-character unique identifier
  receivedAt: string;   // ISO 8601 timestamp
}
```

#### `PaginationInfo`
Metadata for paginating email lists.
```typescript
interface PaginationInfo {
  page: number;
  limit: number;
  totalEmails: number;
  totalPages: number;
  hasMore: boolean;
}
```

#### `InboxResponse`
The response structure for retrieving an inbox.
```typescript
interface InboxResponse {
  emails: StoredEmail[];
  pagination: PaginationInfo;
}
```

#### `SpamResult`
The result of a spam detection check.
```typescript
interface SpamResult {
  isSpam: boolean;
  reason: string | null;
}
```
```

--------------------------------

### Retrieve Inbox Emails via REST API

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Fetches all emails for a specific address using pagination. Supports optional query parameters for page number and limit.

```bash
curl -X GET "http://localhost:3000/api/inbox/swift.falcon42@yourdomain.com"
curl -X GET "http://localhost:3000/api/inbox/swift.falcon42@yourdomain.com?page=2&limit=25"
```

--------------------------------

### Redis Email Storage Functions

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Low-level functions for storing and retrieving emails using Redis. Emails are stored with automatic TTL expiration, and inbox indexes use sorted sets for efficient pagination.

```APIDOC
## Redis Email Storage Functions

### Description
Provides low-level functions for storing and retrieving emails using Redis. Emails are stored as hashes with automatic TTL expiration, and inbox indexes use sorted sets for efficient pagination.

### Functions
- `storeEmail(email)`: Stores a new email.
- `getInbox(emailAddress, page, limit)`: Retrieves inbox emails with pagination.
- `getEmail(emailId)`: Retrieves a single email by its ID.
- `deleteInbox(emailAddress)`: Deletes all emails for a given inbox.
- `deleteEmail(emailId)`: Deletes a single email by its ID.
- `isRedisHealthy()`: Checks if the Redis connection is healthy.

### Request Example (storeEmail)
```typescript
import { storeEmail } from './store';
import type { InboundEmail } from './types';

const email: InboundEmail = {
  to: 'swift.falcon42@yourdomain.com',
  from: 'sender@example.com',
  subject: 'Test Email',
  text: 'Plain text content',
  html: '<p>HTML content</p>',
  headers: { 'content-type': 'text/html' }
};
const emailId = await storeEmail(email);
// Returns: "a1b2c3d4e5f6g7h8i9j0"
```

### Request Example (getInbox)
```typescript
import { getInbox } from './store';
import type { InboxResponse } from './types';

const inbox: InboxResponse = await getInbox('swift.falcon42@yourdomain.com', 1, 10);
// inbox.emails: StoredEmail[]
// inbox.pagination: { page, limit, totalEmails, totalPages, hasMore }
```

### Request Example (getEmail)
```typescript
import { getEmail } from './store';
import type { StoredEmail } from './types';

const stored: StoredEmail | null = await getEmail('a1b2c3d4e5f6g7h8i9j0');
```

### Request Example (deleteInbox)
```typescript
import { deleteInbox } from './store';

const { deleted: count } = await deleteInbox('swift.falcon42@yourdomain.com');
```

### Request Example (deleteEmail)
```typescript
import { deleteEmail } from './store';

const { deleted: success } = await deleteEmail('a1b2c3d4e5f6g7h8i9j0');
```

### Request Example (isRedisHealthy)
```typescript
import { isRedisHealthy } from './store';

const healthy = await isRedisHealthy(); // true if PING returns PONG
```
```

--------------------------------

### Random Email Address Prefix Generation in TypeScript

Source: https://context7.com/dreamshive/cloakmail/llms.txt

This TypeScript function generates human-readable random email prefixes by combining adjectives and nouns, followed by a two-digit number. These prefixes are used to create memorable temporary email addresses. The function utilizes predefined word pools for adjectives and nouns.

```typescript
import { generateRandomPrefix } from '@cloakmail/web';

// Generate a random address prefix
const prefix = generateRandomPrefix();
// Examples: "bold.tiger23", "cosmic.raven87", "neon.phantom12"

const fullAddress = `${prefix}@yourdomain.com`;
// Result: "swift.falcon42@yourdomain.com"

// Word pools used for generation:
// Adjectives: fast, swift, vibrant, silent, shadow, cosmic, bold, dark,
//             bright, clever, lucky, noble, wild, calm, steel, iron, neon, crimson
// Nouns: tiger, falcon, wolf, hawk, phantom, viper, raven, storm,
//        blaze, frost, cipher, ghost, knight, spark, ember, orbit, pulse, nexus
```

--------------------------------

### Check Service Health

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Retrieves the operational status of the SMTP server, Redis connection, and process uptime.

```bash
curl -X GET "http://localhost:3000/api/health"
```

--------------------------------

### Delete Inbox or Single Email

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Operations to remove either an entire inbox or a specific email message. These actions are irreversible and remove data from the Redis storage layer.

```bash
curl -X DELETE "http://localhost:3000/api/inbox/swift.falcon42@yourdomain.com"
curl -X DELETE "http://localhost:3000/api/email/a1b2c3d4e5f6g7h8i9j0"
```

--------------------------------

### DELETE /api/inbox/{address}

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Deletes all emails associated with a specific inbox address.

```APIDOC
## DELETE /api/inbox/{address}

### Description
Removes all emails currently stored in the specified inbox.

### Method
DELETE

### Endpoint
/api/inbox/{address}

### Parameters
#### Path Parameters
- **address** (string) - Required - The email address to clear.

### Response
#### Success Response (200)
- **deleted** (number) - The count of deleted emails.

#### Response Example
{
  "deleted": 5
}
```

--------------------------------

### DELETE /api/email/:id

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Deletes a specific email by its unique identifier.

```APIDOC
## DELETE /api/email/:id

### Description
Deletes a specific email by its unique identifier and removes it from the inbox index.

### Method
DELETE

### Endpoint
/api/email/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the email.

### Response
#### Success Response (200)
- **deleted** (boolean) - True if the email was found and deleted, false otherwise.
```

--------------------------------

### DELETE /api/inbox/:email

Source: https://context7.com/dreamshive/cloakmail/llms.txt

Deletes all emails associated with a specific email address.

```APIDOC
## DELETE /api/inbox/:email

### Description
Deletes all emails associated with a specific email address. This operation is irreversible.

### Method
DELETE

### Endpoint
/api/inbox/:email

### Parameters
#### Path Parameters
- **email** (string) - Required - The email address to clear.

### Response
#### Success Response (200)
- **deleted** (integer) - The count of deleted emails.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.