{ "openapi": "3.0.3", "info": { "title": "Qvicom Mail & Private Aliases API", "version": "2.5.0", "description": "Production RESTful API for provisioning mailboxes, minting private shield aliases on the fly, inbound webhook processing, DKIM outbound signing, cron telemetry, DMARC reports, BIMI verification, mailbox storage archival, Sieve routing rules, threat quarantine, outbound mail spooling, team directory CardDAV vCard sync, disaster recovery snapshots, scoped developer API tokens, DNSBL reputation audits, public status badges, and platform self-healing.", "contact": { "name": "Qvicom Hosting & Cloud Studio Support", "email": "support@qvicom.io", "url": "https://qvicom.io/hosting" } }, "servers": [ { "url": "https://qvicom.io", "description": "Active Qvicom Hosting Server" } ], "components": { "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Qvicom-Key" }, "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "paths": { "/api/v1/health": { "get": { "summary": "API Health & Status", "description": "Checks API platform health, backend mail provider status, and version.", "responses": { "200": { "description": "System is operational and responsive." } } } }, "/api/v1/system/ping": { "get": { "summary": "Deep System Diagnostics & Health Ping", "description": "Comprehensive latency, database ping, filesystem permissions, OpenSSL crypto availability, and memory consumption.", "responses": { "200": { "description": "All platform subsystems verified healthy." }, "503": { "description": "One or more subsystems degraded." } } } }, "/api/v1/system/cron": { "get": { "summary": "Cron Automation Heartbeat Telemetry", "description": "Returns execution heartbeats and health status for background automation jobs.", "responses": { "200": { "description": "Cron tasks telemetry." } } } }, "/api/v1/system/self-heal": { "post": { "summary": "Platform Diagnostics & Automated Self-Healing", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "description": "Executes automated repairs, checks critical directories, syncs schemas, purges expired security tokens, and optimizes database storage.", "responses": { "200": { "description": "Self-healing diagnostic check executed." }, "401": { "description": "Unauthorized." } } } }, "/api/v1/dns/bimi": { "get": { "summary": "BIMI Brand Avatar Status & Eligibility", "description": "Calculates Brand Indicators for Message Identification (BIMI) readiness, checks DMARC quarantine/reject enforcement, validates SVG format, and generates authoritative DNS TXT records.", "responses": { "200": { "description": "BIMI status and DNS TXT record." } } } }, "/api/v1/templates": { "get": { "summary": "List Studio Transactional Email Templates", "description": "Returns list of available branded email templates (Welcome, Receipt, Security Alert, Verification Code).", "responses": { "200": { "description": "List of templates." } } } }, "/api/v1/templates/render": { "post": { "summary": "Render Responsive HTML Email Template", "description": "Renders a complete, email-client compatible inline HTML email with custom parameters and Qvicom branding.", "responses": { "200": { "description": "Rendered HTML and metadata." } } } }, "/api/v1/rules": { "get": { "summary": "List Inbound Sieve & Routing Rules", "description": "Returns all configured inbound sieve rules with trigger conditions and routing actions.", "responses": { "200": { "description": "List of rules." } } } }, "/api/v1/quarantine": { "get": { "summary": "List Threat Quarantine Vault Items", "description": "Returns isolated suspicious messages and phishing attempts currently held in the security quarantine.", "responses": { "200": { "description": "List of quarantined threats." } } } }, "/api/v1/dkim/sign": { "post": { "summary": "Cryptographic DKIM Outbound Message Signing", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "description": "Generates RFC 6376 2048-bit RSA DKIM signature header for a given email.", "responses": { "200": { "description": "DKIM signature created." }, "401": { "description": "Unauthorized." } } } }, "/api/v1/mailboxes": { "get": { "summary": "List Mailboxes", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "description": "Returns list of provisioned email accounts and storage allocations.", "responses": { "200": { "description": "List of mailboxes." }, "401": { "description": "Unauthorized." } } }, "post": { "summary": "Create Mailbox", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "description": "Provisions a new domain mailbox with credentials and quota.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "password" ], "properties": { "domain": { "type": "string", "example": "qvicom.io" }, "username": { "type": "string", "example": "clientcare" }, "name": { "type": "string", "example": "Client Care Desk" }, "password": { "type": "string", "example": "Secret2026!" }, "quota_mb": { "type": "integer", "example": 5120 } } } } } }, "responses": { "201": { "description": "Mailbox provisioned successfully." }, "400": { "description": "Invalid parameters." } } } }, "/api/v1/mailboxes/archive/{id}": { "post": { "summary": "Archive Mailbox Messages (.mbox)", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "description": "Generates an RFC 4155 .mbox archive file and optionally purges messages to reclaim storage quota.", "responses": { "200": { "description": "Archival completed and metadata returned." }, "404": { "description": "Mailbox not found." } } } }, "/api/v1/mailboxes/{id}/warmup": { "get": { "summary": "Mailbox Deliverability Warmup Schedule", "description": "Returns active 30-day volume ramp curve, current day target limits, daily sent counts, and inbox placement benchmarks across Google, Microsoft, and Apple.", "responses": { "200": { "description": "Warmup schedule and reputation metrics." } } } }, "/api/v1/webmail/messages": { "get": { "summary": "Webmail Message Store and Search", "description": "Queries stored webmail messages with support for folder filtering (inbox, starred, sent, trash, all) and full-text keyword search across sender, subject, and snippet.", "parameters": [ { "name": "mailbox_id", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "folder", "in": "query", "schema": { "type": "string", "default": "inbox" } }, { "name": "q", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of matching webmail messages." } } } }, "/api/v1/webmail/messages/star/{id}": { "post": { "summary": "Toggle Message Star / Flag", "description": "Stars or unstars a specific webmail message.", "responses": { "200": { "description": "Star status updated." } } } }, "/api/v1/webmail/messages/read/{id}": { "post": { "summary": "Toggle Message Read Status", "description": "Toggles read or unread state of a webmail message.", "responses": { "200": { "description": "Read status updated." } } } }, "/api/v1/webmail/messages/spam/{id}": { "post": { "summary": "Isolate Threat into Quarantine Vault", "description": "Flags an inbound email as malicious phishing or spam, triggers SecurityShield heuristics, and moves the envelope into the Quarantine Vault.", "responses": { "200": { "description": "Message successfully quarantined." } } } }, "/api/v1/webmail/sync": { "post": { "summary": "Live IMAP Sync Telemetry", "description": "Performs an on-demand SSL socket verification against Hostinger Cloud IMAP (imap.hostinger.com:993) and returns mailbox sync latency and envelope counts.", "responses": { "200": { "description": "IMAP handshake and sync report." } } } }, "/api/v1/webmail/batch": { "post": { "summary": "Batch Message Operations", "description": "Executes bulk actions (delete, star, unstar, mark_read, mark_unread) across multiple message IDs simultaneously.", "responses": { "200": { "description": "Batch processing results and count of affected messages." } } } }, "/api/v1/bounces": { "get": { "summary": "List Suppressed Bounces", "description": "Returns active suppression list with classification breakdown (hard, soft, complaints).", "responses": { "200": { "description": "List of suppressed recipients." } } }, "post": { "summary": "Add Recipient to Suppression List", "description": "Manually suppresses an email address from receiving outbound mail.", "responses": { "200": { "description": "Address successfully suppressed." } } } }, "/api/v1/bounces/remove": { "post": { "summary": "Unsuppress Recipient", "description": "Removes an email address from the suppression list, allowing future sends.", "responses": { "200": { "description": "Address removed from suppression list." } } } }, "/api/v1/bounces/process": { "post": { "summary": "Process RFC 3464 DSN Payload", "description": "Ingests a raw bounce Delivery Status Notification and auto-suppresses permanent failures.", "responses": { "200": { "description": "DSN parsed and processed." } } } }, "/api/v1/aliases": { "get": { "summary": "List Private Aliases", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "description": "Returns all active private shield aliases with forwarding statistics.", "responses": { "200": { "description": "List of aliases." } } }, "post": { "summary": "Mint Private Shield Alias", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "description": "Generates or provisions a private alias with destination routing.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "example": "qvicom.io" }, "label": { "type": "string", "example": "Client Checkout Privacy" }, "category": { "type": "string", "example": "shop" }, "destinations": { "type": "string", "example": "sales@qvicom.store" }, "custom_slug": { "type": "string", "example": "order-491" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "responses": { "201": { "description": "Alias generated successfully." } } } }, "/api/v1/inbound": { "post": { "summary": "Inbound Email Webhook", "description": "Webhook endpoint for processing incoming email messages, stripping tracking beacons, and forwarding.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to", "from" ], "properties": { "to": { "type": "string", "example": "priv.aws-cloud@qvicom.io" }, "from": { "type": "string", "example": "alerts@aws.amazon.com" }, "subject": { "type": "string", "example": "Security Hub Alert" }, "html": { "type": "string", "example": "

Alert details

" }, "text": { "type": "string", "example": "Alert details" } } } } } }, "responses": { "200": { "description": "Email processed and routed." }, "422": { "description": "Email rejected (spam or alias paused)." } } } }, "/api/v1/dns/verify/{domain}": { "get": { "summary": "Verify Domain DNS", "description": "Performs live DNS queries against authoritative name servers for MX, SPF, DKIM, and DMARC.", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "example": "qvicom.io" } } ], "responses": { "200": { "description": "DNS health verification report." } } } }, "/api/v1/dns/reputation/{domain}": { "get": { "summary": "Domain Reputation & DNSBL Anti-Spam Audit", "description": "Performs real-time reputation scoring (0-100%) and multi-network DNSBL blacklist checks (Spamhaus, Barracuda, SpamCop, SORBS).", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "example": "qvicom.io" } } ], "responses": { "200": { "description": "Domain reputation and DNSBL audit results." } } } }, "/api/v1/queue": { "get": { "summary": "Outbound Mail Queue & Spooler", "description": "Returns queue metrics, telemetry, and pending outbound messages waiting in spooler.", "responses": { "200": { "description": "Queue statistics and list of spool jobs." } } } }, "/api/v1/queue/flush": { "post": { "summary": "Flush Pending Mail Queue Batch", "description": "Immediately processes up to N pending outbound messages with rate limiting and exponential backoff.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "batch": { "type": "integer", "example": 25 } } } } } }, "responses": { "200": { "description": "Queue batch process results." } } } }, "/api/v1/contacts": { "get": { "summary": "Global Address List & Team Directory", "description": "Retrieves verified corporate mailboxes and custom team contacts.", "responses": { "200": { "description": "List of corporate contacts." } } } }, "/api/v1/contacts/vcard": { "get": { "summary": "Export RFC 6350 CardDAV vCard 4.0 Stream", "description": "Exports all corporate contacts as a standardized .vcf file for Apple iOS, macOS, Outlook, and Google Contacts.", "responses": { "200": { "description": "vCard 4.0 MIME stream." } } } }, "/api/v1/system/backups": { "get": { "summary": "List Platform Disaster Recovery Snapshots", "description": "Returns list of point-in-time system backup archives with SHA-256 hashes and file sizes.", "responses": { "200": { "description": "List of system snapshots." } } } }, "/api/v1/system/backups/create": { "post": { "summary": "Generate Disaster Recovery Snapshot", "description": "Creates a complete point-in-time backup archive of database, routing rules, quarantine vault, and settings.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "example": "Pre-Deployment Snapshot" } } } } } }, "responses": { "200": { "description": "Snapshot generated successfully." } } } }, "/api/v1/system/status": { "get": { "summary": "Public Platform Status & Uptime", "description": "Returns real-time operational status, component health, and rolling 90-day uptime metrics.", "responses": { "200": { "description": "Platform operational status report." } } } }, "/api/v1/system/badge.svg": { "get": { "summary": "Dynamic Status SVG Badge", "description": "Returns an embeddable SVG image reflecting current platform health (operational vs degraded).", "responses": { "200": { "description": "SVG badge image stream." } } } }, "/api/v1/system/keys": { "get": { "summary": "List Active Scoped API Keys", "description": "Returns list of non-sensitive scoped API key metadata and granted capabilities.", "responses": { "200": { "description": "List of active API keys." } } }, "post": { "summary": "Generate Scoped API Key", "description": "Mints a new high-entropy API key with specific capability scopes.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "CI/CD Provisioner" }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "mailboxes:read", "queue:flush" ] } } } } } }, "responses": { "200": { "description": "API Key created successfully." } } } } } }