Abuse Control & Rate Limiting

Relevant source files

The following files were used as context for generating this wiki page:

• services/api/src/routes/abuse.ts
• services/api/prisma/migrations/0002_abuse_controls/migration.sql
• services/api/src/worker.ts
• services/web/src/components/AdminPanel.tsx
• services/web/src/pages/Legal/AcceptableUse.tsx
• README.md
• services/api/src/routes/billing.ts
• services/web/src/components/admin/AdminReports.tsx
• blueprint.md

The email-platform incorporates a multi-layered abuse control and rate-limiting system to ensure service stability, prevent misuse, and maintain a good reputation. This system is designed to be robust and configurable, providing administrators with the tools to manage platform usage effectively. Key pillars of this system include dynamic allow/block rules, SMTP rate limits, resource quotas based on user tiers, and a user-driven abuse reporting mechanism.

These controls are critical for any public-facing email service to mitigate risks such as spam, fraud, and denial-of-service attacks. The implementation spans across the API, the email processing worker, and the admin-facing web UI.

Sources: README.md:104-107, blueprint.md:100-104

1. System Architecture Overview

The abuse control system is integrated directly into the inbound email processing pipeline. When an email is received, it undergoes several checks before being stored and delivered to an inbox. This includes rule evaluation, rate limit enforcement, and quota checks.

This diagram illustrates the high-level flow of an inbound email and where abuse control mechanisms are applied.

2. Database Schema

The abuse control features are supported by two primary database tables: Rule and AbuseReport. These tables store the configuration for dynamic filtering and track user-submitted reports.

Sources: services/api/prisma/migrations/0002_abuse_controls/migration.sql

This ER diagram shows the relationship between the Rule, AbuseReport, and Message tables.

2.1. Rule Table

This table stores dynamic allow/block rules managed by administrators.

Column	Type	Description
id	TEXT	Primary key (UUID).
type	RuleType	The action to take: ALLOW or BLOCK.
scope	RuleScope	The entity to match against: SENDER_DOMAIN, SENDER_EMAIL, RECIPIENT_DOMAIN, RECIPIENT_INBOX, SOURCE_IP.
value	TEXT	The value to match (e.g., 'spam.com', '1.2.3.4').
note	TEXT	An optional administrative note.
expiresAt	TIMESTAMP	An optional expiration date for the rule.

Sources: services/api/prisma/migrations/0002_abuse_controls/migration.sql:11-20

2.2. AbuseReport Table

This table stores reports of abuse submitted by users or the system.

Column	Type	Description
id	TEXT	Primary key (UUID).
messageId	TEXT	Foreign key to the Message table (optional).
reporter	TEXT	The email address of the person reporting (optional).
reason	TEXT	The reason for the report.
status	AbuseReportStatus	The current status of the report: OPEN, REVIEWING, CLOSED.

Sources: services/api/prisma/migrations/0002_abuse_controls/migration.sql:24-32

3. Dynamic Rule System

Administrators can create dynamic rules to BLOCK or ALLOW emails based on various criteria. These rules are evaluated by the email worker before an email is accepted.

Sources: services/api/src/routes/abuse.ts:10-35, services/api/src/worker.ts:199-206

3.1. Rule Evaluation Flow

The evaluateRules function in the email worker checks incoming emails against the configured rules.

3.2. Rule Management API

The /abuse/rules endpoints allow administrators to manage these rules. All endpoints require admin privileges.

Method	Endpoint	Description
GET	/abuse/rules	Retrieves all existing rules.
POST	/abuse/rules	Creates a new rule.
DELETE	/abuse/rules/:id	Deletes a rule by its ID.

Sources: services/api/src/routes/abuse.ts:10-53

The POST endpoint for creating a rule expects a specific payload, validated using Zod.

// Source: services/api/src/routes/abuse.ts:15-23
const body = z
  .object({
    type: z.nativeEnum(RuleType),
    scope: z.nativeEnum(RuleScope),
    value: z.string().min(1),
    note: z.string().optional(),
    expiresAt: z.string().datetime().optional(),
  })

3.3. Admin UI for Rules

The Admin Panel provides a user interface for managing these rules under the "Quy tắc bảo vệ" (Protection Rules) tab. It allows admins to view, add, and delete rules.

• View Rules: A table lists all active rules with their type, scope, and value.
• Add Rule: A form allows creating new rules by selecting a type (BLOCK/ALLOW), scope, and providing a value.
• Delete Rule: Each rule has a "Xóa" (Delete) button.

Sources: services/web/src/components/AdminPanel.tsx:180-282

4. Rate Limiting and Quotas

The platform employs several layers of rate limiting and quotas to ensure fair usage and prevent system overload.

4.1. SMTP Inbound Rate Limits

These limits are enforced during email processing to control the volume of incoming mail from any single source. The limits are checked within a 5-minute window.

Resource	Limit (per 5 minutes)
Emails per IP	300
Emails per domain	500
Emails per inbox	200

The enforceRateLimits function in the email worker queries the Message table to count recent emails and throws an error if a limit is exceeded.

Sources: services/web/src/pages/Legal/AcceptableUse.tsx:81-95, services/api/src/worker.ts:153-176

4.2. Tier-Based Resource Quotas

In addition to real-time rate limits, the system enforces hard quotas on the number of domains and inboxes a user can create based on their subscription tier. These checks are performed via a Fastify preHandler hook before creating new resources.

Tier	Domains	Inboxes	Daily Emails
FREE	1	3	50
STARTER	3	20	200
PROFESSIONAL	10	100	1000
ENTERPRISE	Unlimited	Unlimited	Unlimited

If a user on the FREE plan attempts to create a second domain, the API will return a 403 Forbidden error.

Sources: services/api/src/routes/billing.ts:13-18, services/api/src/routes/billing.ts:289-335

4.3. Attachment Restrictions

To control storage and mitigate security risks, attachments are also limited.

• Max Size: 5MB
• Allowed Types: The system can be configured with a list of allowed MIME type prefixes (e.g., image/) and file extensions.

Sources: services/web/src/pages/Legal/AcceptableUse.tsx:96-99, services/api/src/worker.ts:114-123

5. Abuse Reporting System

Users can report emails they consider abusive. These reports are managed by administrators through the Admin Panel.

5.1. Reporting Flow

The following diagram shows the sequence of creating and managing an abuse report.

5.2. Abuse Report API

The /abuse/reports endpoints facilitate the reporting and management process.

Method	Endpoint	Authentication	Description
POST	/abuse/reports	Optional (User or Anonymous)	Submits a new abuse report.
GET	/abuse/reports	Admin Required	Retrieves all abuse reports.
PATCH	/abuse/reports/:id	Admin Required	Updates the status of a specific report.

Sources: services/api/src/routes/abuse.ts:70-142

5.3. Admin UI for Reports

The "Báo cáo vi phạm" (Abuse Reports) section in the Admin Panel lists all submitted reports. Administrators can filter reports by status (OPEN, REVIEWING, CLOSED) and update the status of each report. The UI displays the reason for the report, who reported it, and details about the associated email message if available.

Sources: services/web/src/components/admin/AdminReports.tsx:24-126

Summary

The abuse control and rate-limiting system is a comprehensive feature set crucial for the platform's health and security. It combines automated, preventative measures like rules and rate limits with reactive tools like the abuse reporting system. The entire system is configurable and manageable through a dedicated admin interface, giving operators the power to adapt to emerging threats and maintain a high-quality service.