API Endpoints
Relevant source files
The following files were used as context for generating this wiki page:The TempMail Pro API is a RESTful service built with Node.js and Fastify, providing comprehensive control over domains, inboxes, and messages. It serves as the backend for the web application and allows for automation and integration. The API uses JWT for authentication, with tokens provided via an Authorization: Bearer <token> header for protected routes.
The core functionality revolves around a multi-tenant architecture where users can manage their own domains, create disposable inboxes under those domains, and view received emails. The API also includes a robust admin panel for user management, system monitoring, and abuse control.
Sources: README.md:19-23, README.md:43-44, blueprint.md:10-14
Health & Monitoring
These endpoints provide information about the API's status and performance metrics, crucial for operational monitoring.
| Method | Path | Description | Auth Required |
|---|---|---|---|
GET | /health | Checks the basic health of the API service. | No |
GET | /ready | Checks if the service is ready to accept traffic (e.g., DB connection is up). | No |
GET | /metrics | Exposes performance metrics in Prometheus format. | No |
Sources: README.md:45, PLAN.md:29
Authentication
Authentication is handled via JWT. A user logs in with their credentials to receive a token, which must be included in subsequent requests to protected endpoints.
Sources: README.md:43-44, services/api/test/api.integration.test.ts:49-52
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /auth/login | Authenticates a user and returns a JWT. |
Sources: README.md:46, blueprint.md:175
Login Flow
The following diagram illustrates the sequence of a user logging in and obtaining an authentication token.
Domains
These endpoints are used to manage custom domains that users add to the platform. A domain must be verified by adding a specific TXT record to its DNS configuration before it can be used to receive emails.
Sources: README.md:47, blueprint.md:176-178
Endpoints
| Method | Path | Description | Auth Required |
|---|---|---|---|
GET | /domains | Lists domains for the authenticated user, with search and pagination. | Yes |
POST | /domains | Adds a new domain and returns a verification token. | Yes |
POST | /domains/:id/verify | Attempts to verify a domain by checking its DNS TXT record. | Yes |
PATCH | /domains/:id | Updates a domain, used for requesting contribution to the shared pool. | Yes |
Sources: README.md:47, services/api/test/api.integration.test.ts:54-58, services/api/src/test/shared_domains.test.ts:70-85
Domain Verification Flow
This diagram shows the process of a user adding and verifying a new domain.
Inboxes
Inboxes are email addresses created under a verified domain. The system supports creating inboxes on demand.
Sources: README.md:48, blueprint.md:179-180
Endpoints
| Method | Path | Description | Auth Required |
|---|---|---|---|
GET | /inboxes | Lists inboxes, filterable by domain, with search and pagination. | Yes |
POST | /inboxes | Creates a new inbox under a specified domain. | Yes |
POST | /public/inboxes | Creates an inbox on a public domain (optional, CAPTCHA-gated). | No |
Sources: README.md:48, services/api/test/api.integration.test.ts:60-64
Messages
This set of endpoints provides full control over reading, searching, and managing email messages within inboxes.
Sources: services/api/src/routes/messages.ts
Endpoints
| Method | Path | Description | Auth Required |
|---|---|---|---|
GET | /inboxes/:id/messages | Retrieves a paginated list of messages for a specific inbox with advanced filtering. | Yes |
GET | /messages/search | Performs a global search for messages across a user's domains. | Yes |
GET | /messages/search/fuzzy | Performs a fuzzy search using pg_trgm for relevance ranking. | Yes |
GET | /messages/:id | Retrieves a single message by its ID. | Yes |
DELETE | /messages/:id | Deletes a message (soft delete). | Yes |
PATCH | /messages/:id/read | Marks a message as read or unread. | Yes |
PATCH | /messages/:id/pin | Pins or unpins a message. | Yes |
PATCH | /messages/:id/snooze | Snoozes a message until a specified datetime. | Yes |
GET | /attachments/:id/download | Downloads an attachment file. | Yes |
GET | /messages/:id/export | Exports a message in .eml format. | Yes |
Sources: README.md:49, services/api/src/routes/messages.ts:4-338
Message Retrieval and Filtering
The GET /inboxes/:id/messages endpoint is the primary way to fetch emails. It supports a rich set of query parameters for filtering and pagination.
| Parameter | Type | Description |
|---|---|---|
limit | number | Number of messages to return (max 200). |
offset | number | Number of messages to skip for pagination. |
q | string | A general search query across subject, from/to addresses, and text body. |
from | string | Filter by sender address. |
subject | string | Filter by subject line. |
start | datetime | Filter for messages received on or after this date. |
end | datetime | Filter for messages received on or before this date. |
hasAttachments | boolean | Filter for messages that have attachments. |
isRead | boolean | Filter by read status. |
Sources: services/api/src/routes/messages.ts:40-56
Billing
The billing endpoints manage user subscriptions and enforce plan limits. The implementation uses a preHandler hook to check tier limits before creating new resources like domains or inboxes.
Sources: services/api/src/routes/billing.ts
Endpoints
| Method | Path | Description | Auth Required |
|---|---|---|---|
GET | /billing | Get the current user's subscription status, limits, and usage. | Yes |
GET | /billing/plans | List available subscription plans and their features. | No |
POST | /billing/checkout | Creates a Stripe checkout session to upgrade a plan. | Yes |
POST | /billing/cancel | Cancels the current active subscription. | Yes |
POST | /billing/webhook | Endpoint for receiving Stripe webhook events. | No |
Sources: services/api/src/routes/billing.ts:38-212
Tier Limit Enforcement
The API automatically prevents users from exceeding their plan's resource limits.
Admin
The admin endpoints are restricted to users with the ADMIN role and provide capabilities for managing the entire platform.
Sources: services/api/src/routes/admin.ts
Endpoints
| Method | Path | Description | Auth Required |
|---|---|---|---|
GET | /admin/stats | Retrieves high-level statistics for the admin dashboard. | Admin |
GET | /admin/stats/timeseries | Gets time-series data (e.g., daily new users/emails) for charts. | Admin |
GET | /admin/users | Lists all users with search and pagination. | Admin |
PATCH | /admin/users/:id | Updates a user's role or disabled status. | Admin |
DELETE | /admin/users/:id | Deletes a user and all their associated data (cascade delete). | Admin |
POST | /admin/users/:id/verify | Force-verifies a user's email address. | Admin |
GET | /admin/audit-logs | Lists system-wide audit logs with filtering. | Admin |
GET | /admin/audit-logs/export | Exports audit logs to a CSV file. | Admin |
GET | /admin/system-info | Provides general system information like server time and resource counts. | Admin |