{ "schemes": ["https"], "swagger": "2.0", "info": { "description": "Mailforge Public API", "title": "Mailforge API", "contact": {}, "version": "1.0" }, "host": "api.mailforge.ai", "basePath": "/public", "paths": { "/adjust-mailbox-topup-amount": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Sets the number of mailbox slots to automatically purchase when the account runs out. Set to 0 to disable auto-topup.", "consumes": [ "application/json" ], "tags": [ "Mailboxes" ], "summary": "Adjust mailbox topup amount", "parameters": [ { "description": "Topup amount", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/api.AdjustMailboxTopupAmountRequest" } } ], "responses": { "204": { "description": "Updated" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/api-keys": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns all API keys belonging to the authenticated account. Requires Firebase Bearer token.\nMust be called without /public prefix", "produces": [ "application/json" ], "tags": [ "API Keys" ], "summary": "List API keys", "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/mailforge_external-api_delivery_api.APIKeyResponse" } } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/api.HTTPError" } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates a new API key for the account. The raw key is returned once and cannot be retrieved again. Requires Firebase Bearer token.\nMust be called without /public prefix", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "API Keys" ], "summary": "Create API key", "parameters": [ { "description": "API key name", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/api.CreateAPIKeyRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/api.CreateAPIKeyResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/api.HTTPError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/api-keys/{apiKeyID}": { "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Permanently deletes an API key. Requires Firebase Bearer token.\nMust be called without /public prefix", "tags": [ "API Keys" ], "summary": "Delete API key", "parameters": [ { "type": "string", "description": "API Key ID", "name": "apiKeyID", "in": "path", "required": true } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/api.HTTPError" } } } }, "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Toggles the active state of an API key. Requires Firebase Bearer token.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "API Keys" ], "summary": "Update API key", "parameters": [ { "type": "string", "description": "API Key ID", "name": "apiKeyID", "in": "path", "required": true }, { "description": "Update payload", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/api.UpdateAPIKeyRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/mailforge_external-api_delivery_api.APIKeyResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/api.HTTPError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/check-domain-availability": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Checks whether a single domain name is available for registration and returns its price.", "produces": [ "application/json" ], "tags": [ "Domains" ], "summary": "Check domain availability", "parameters": [ { "type": "string", "description": "Domain name (e.g. example.com)", "name": "domain", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/mailforge_external-api_delivery_api.DomainAvailabilityResponse" } }, "400": { "description": "domain query parameter is required", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/check-domain-availability-bulk": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Checks availability and pricing for up to 100 domain names at once.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Domains" ], "summary": "Bulk check domain availability", "parameters": [ { "description": "List of domain names", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/mailforge_external-api_delivery_api.CheckDomainAvailabilityBulkRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/mailforge_external-api_delivery_api.DomainAvailabilityResponse" } } }, "400": { "description": "Maximum 100 domains allowed", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/domains": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns all domains belonging to the account. Optionally filtered by status or search query.", "produces": [ "application/json" ], "tags": [ "Domains" ], "summary": "List domains", "parameters": [ { "enum": [ "active", "pending", "failed", "expired", "scheduled_for_deletion", "not_paid" ], "type": "string", "description": "Filter by status", "name": "status", "in": "query" }, { "type": "string", "description": "Search domains by id, workspace id, domain name, forward-to domain, or status", "name": "search", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/mailforge_external-api_delivery_api.DomainResponse" } } }, "400": { "description": "Invalid domain status", "schema": { "$ref": "#/definitions/api.HTTPError" } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Purchases one or more domain names, creates DNS records, and triggers registration. Contact details are used for WHOIS registration.\nFor some ccTLDs (e.g. .eu), pass required Enom extended attributes in contactDetails.extra (discover via GET /public/domains/extra-fields). Missing required extras return 400 before charging.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Domains" ], "summary": "Purchase domains", "parameters": [ { "description": "Purchase request", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/api.BuyDomainsRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/api.BuyDomainsResponse" } }, "400": { "description": "Domain not available, invalid request, or missing required contactDetails.extra fields", "schema": { "$ref": "#/definitions/api.HTTPError" } }, "402": { "description": "No payment method on file", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/domains/alternative-domains": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Proposes up to `count` available alternative domain names for the given SLD and TLD. Does not create or reserve domains. Excludes domains already active on the account.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Domains" ], "summary": "Suggest alternative domains", "parameters": [ { "description": "inputSld, count, outputTld", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/api.SuggestAlternativeDomainsRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/mailforge_external-api_delivery_api.DomainAvailabilityResponse" } } }, "400": { "description": "Invalid request or unsupported TLD", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/domains/bulk-disable-autorenew": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Disables automatic renewal for multiple domains.", "consumes": [ "application/json" ], "tags": [ "Domains" ], "summary": "Bulk disable auto-renew", "parameters": [ { "description": "Domain IDs", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/api.BulkAutoRenewRequest" } } ], "responses": { "204": { "description": "Updated" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/domains/bulk-dns": { "put": { "security": [ { "ApiKeyAuth": [] } ], "description": "Updates DNS records for multiple domains at once.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Domains" ], "summary": "Bulk update DNS", "parameters": [ { "description": "DNS update payload", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/models.DNSUpdatePayload" } } ], "responses": { "202": { "description": "Accepted" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/domains/bulk-enable-autorenew": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Enables automatic renewal for multiple domains.", "consumes": [ "application/json" ], "tags": [ "Domains" ], "summary": "Bulk enable auto-renew", "parameters": [ { "description": "Domain IDs", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/api.BulkAutoRenewRequest" } } ], "responses": { "204": { "description": "Updated" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/domains/extra-fields": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns Enom-required extended attributes for the given TLDs (union across all requested TLDs). Use the returned field names/values in contactDetails.extra when purchasing domains via POST /public/domains.", "produces": [ "application/json" ], "tags": [ "Domains" ], "summary": "Get required domain extra fields", "parameters": [ { "type": "string", "description": "Comma-separated TLDs (e.g. eu,de)", "name": "tlds", "in": "query" }, { "type": "string", "description": "Comma-separated FQDNs; TLDs are derived (e.g. example.eu,foo.de)", "name": "domains", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/api.ExtraDomainFieldResponse" } } }, "400": { "description": "tlds or domains query parameter is required", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/domains/forwards": { "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Sets or updates the forwarding address for one or more domains.", "consumes": [ "application/json" ], "tags": [ "Domains" ], "summary": "Update domain forwards", "parameters": [ { "description": "Forward settings", "name": "body", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/mailforge_external-api_delivery_api.UpdateDomainForwardsRequest" } } } ], "responses": { "204": { "description": "Updated" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/domains/masking": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Purchases domain masking/SSL redirect for one or more domains.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Domains" ], "summary": "Purchase domain masking (SSL redirect)", "parameters": [ { "description": "Masking request", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/api.PurchaseDomainMaskingRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/mailforge_external-api_delivery_api.DomainMaskingResponse" } } }, "400": { "description": "Invalid request or no domains found", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/domains/pre-warmed": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Purchase pre-warmed domains (and their bundled mailboxes) and attach them to the workspace. Charges the account directly (no checkout redirect) and requires an active subscription. Returns the attached domains, mailboxes, setup and the resulting invoice.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Domains" ], "summary": "Purchase pre-warmed domains", "parameters": [ { "description": "Pre-warmed purchase request", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/api.ExternalPurchasePreWarmedDomainsRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/api.ExternalBuyPreWarmedDomainsResponse" } }, "400": { "description": "Invalid request or no active subscription", "schema": { "$ref": "#/definitions/api.HTTPError" } }, "404": { "description": "Workspace or domains not found", "schema": { "$ref": "#/definitions/api.HTTPError" } }, "409": { "description": "Unpaid Mailforge subscription balance; code: unpaid_subscription_balance. Settle outstanding invoices before subscribing again.", "schema": { "$ref": "#/definitions/api.SubscriptionBalanceError" } } } } }, "/domains/transfer": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Initiates transfer of existing domains into the account. Response matches Infraforge (domains + optional invoice object). If every domain already exists in the workspace, no invoice is created (allDomainsAlreadyInWorkspace=true) and non-active domains are registered when possible.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Domains" ], "summary": "Transfer domains", "parameters": [ { "description": "Transfer request", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/api.CreateDomainTransferRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/mailforge_external-api_delivery_api.CreateDomainTransferResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/domains/{domainID}/disable-autorenew": { "put": { "security": [ { "ApiKeyAuth": [] } ], "description": "Disables automatic renewal for the specified domain.", "tags": [ "Domains" ], "summary": "Disable auto-renew for a domain", "parameters": [ { "type": "string", "description": "Domain ID", "name": "domainID", "in": "path", "required": true } ], "responses": { "204": { "description": "Updated" }, "404": { "description": "Domain not found", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/domains/{domainID}/dns": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns all DNS records for a domain.", "produces": [ "application/json" ], "tags": [ "Domains" ], "summary": "Get domain DNS records", "parameters": [ { "type": "string", "description": "Domain ID", "name": "domainID", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/api.DomainRecordResponse" } } }, "404": { "description": "Domain not found", "schema": { "$ref": "#/definitions/api.HTTPError" } } } }, "put": { "security": [ { "ApiKeyAuth": [] } ], "description": "Replaces DNS records for a domain.", "consumes": [ "application/json" ], "tags": [ "Domains" ], "summary": "Update domain DNS records", "parameters": [ { "type": "string", "description": "Domain ID", "name": "domainID", "in": "path", "required": true }, { "description": "DNS records", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/api.UpdateDomainDNSRequest" } } ], "responses": { "204": { "description": "Updated" }, "400": { "description": "Invalid DNS configuration", "schema": { "$ref": "#/definitions/api.HTTPError" } }, "404": { "description": "Domain not found", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/domains/{domainID}/enable-autorenew": { "put": { "security": [ { "ApiKeyAuth": [] } ], "description": "Enables automatic renewal for the specified domain.", "tags": [ "Domains" ], "summary": "Enable auto-renew for a domain", "parameters": [ { "type": "string", "description": "Domain ID", "name": "domainID", "in": "path", "required": true } ], "responses": { "204": { "description": "Updated" }, "404": { "description": "Domain not found", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/domains/{domainID}/masking": { "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Removes domain masking/SSL redirect from a domain.", "tags": [ "Domains" ], "summary": "Delete domain masking", "parameters": [ { "type": "string", "description": "Domain ID", "name": "domainID", "in": "path", "required": true } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Domain not found", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/mailboxes": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns all mailboxes belonging to the account.", "produces": [ "application/json" ], "tags": [ "Mailboxes" ], "summary": "List mailboxes", "parameters": [ { "type": "boolean", "description": "Include IMAP/SMTP credentials in the response", "name": "with_credentials", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/mailforge_external-api_delivery_api.MailboxResponse" } } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates one or more mailboxes. Additional slots are purchased automatically if the account's limit is reached.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Mailboxes" ], "summary": "Purchase mailboxes", "parameters": [ { "description": "Mailbox creation request", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/mailforge_external-api_delivery_api.BuyMailboxesRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/mailforge_external-api_delivery_api.BuyMailboxesResponse" } }, "400": { "description": "Invalid request or mailbox limit exceeded", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/mailboxes/bulk-forward": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Sets a forwarding email address for multiple mailboxes matching the given filter.", "consumes": [ "application/json" ], "tags": [ "Mailboxes" ], "summary": "Bulk forward mailboxes", "parameters": [ { "description": "Bulk forward request", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/api.BulkForwardMailboxesRequest" } } ], "responses": { "202": { "description": "Accepted" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/mailboxes/pre-warmed": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "List available pre-warmed domains with their bundled mailboxes and flat per-domain price. Supports search by domain name and pagination. Omit limit to use the default of 100.", "produces": [ "application/json" ], "tags": [ "Mailboxes" ], "summary": "List available pre-warmed domains", "parameters": [ { "type": "string", "description": "Search by domain name", "name": "search", "in": "query" }, { "type": "integer", "description": "Maximum number of domains to return (1-100). Defaults to 100 when omitted.", "name": "limit", "in": "query" }, { "type": "integer", "description": "Number of domains to skip", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/api.ExternalGetPreWarmedDomainsListResponse" } }, "400": { "description": "Invalid request (e.g. limit out of range)", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/mailboxes/{mailboxID}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns a single mailbox by ID.", "produces": [ "application/json" ], "tags": [ "Mailboxes" ], "summary": "Get mailbox", "parameters": [ { "type": "string", "description": "Mailbox ID", "name": "mailboxID", "in": "path", "required": true }, { "type": "boolean", "description": "Include IMAP/SMTP credentials in the response", "name": "with_credentials", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/mailforge_external-api_delivery_api.MailboxResponse" } }, "404": { "description": "Mailbox not found", "schema": { "$ref": "#/definitions/api.HTTPError" } } } }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Permanently deletes a mailbox.", "tags": [ "Mailboxes" ], "summary": "Delete mailbox", "parameters": [ { "type": "string", "description": "Mailbox ID", "name": "mailboxID", "in": "path", "required": true } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Mailbox not found", "schema": { "$ref": "#/definitions/api.HTTPError" } } } }, "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Updates mailbox fields such as name, signature, password, or forwarding email.", "consumes": [ "application/json" ], "tags": [ "Mailboxes" ], "summary": "Update mailbox", "parameters": [ { "type": "string", "description": "Mailbox ID", "name": "mailboxID", "in": "path", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/models.UpdateMailboxPayload" } } ], "responses": { "204": { "description": "Updated" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/api.HTTPError" } }, "404": { "description": "Mailbox not found", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/spam-check/is-spam": { "post": { "description": "Returns true if the email content is similar to a known suspicious email.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "spam-check" ], "summary": "Check whether an email is spam", "parameters": [ { "description": "Email content", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/spamcheck.CheckRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/http.isSpamResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/workspaces": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns all workspaces belonging to the account.", "produces": [ "application/json" ], "tags": [ "Workspaces" ], "summary": "List workspaces", "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/api.WorkspaceResponse" } } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates a new workspace under the account.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Workspaces" ], "summary": "Create workspace", "parameters": [ { "description": "Workspace name", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/mailforge_external-api_delivery_api.CreateWorkspaceRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/api.WorkspaceResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/workspaces/{workspaceID}": { "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Permanently deletes a workspace and all its associated resources.", "tags": [ "Workspaces" ], "summary": "Delete workspace", "parameters": [ { "type": "string", "description": "Workspace ID", "name": "workspaceID", "in": "path", "required": true } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Workspace not found", "schema": { "$ref": "#/definitions/api.HTTPError" } } } }, "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Updates the name of an existing workspace.", "consumes": [ "application/json" ], "tags": [ "Workspaces" ], "summary": "Update workspace", "parameters": [ { "type": "string", "description": "Workspace ID", "name": "workspaceID", "in": "path", "required": true }, { "description": "Updated fields", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/api.UpdateWorkspaceRequest" } } ], "responses": { "204": { "description": "Updated" }, "404": { "description": "Workspace not found", "schema": { "$ref": "#/definitions/api.HTTPError" } } } } }, "/workspaces/{workspaceID}/mailboxes/analytics/summary": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Per-mailbox sent, received and daily trend for the mailbox list page", "produces": [ "application/json" ], "tags": [ "Mailboxes" ], "summary": "Get mailbox analytics summary", "parameters": [ { "type": "string", "description": "Workspace ID", "name": "workspaceID", "in": "path", "required": true }, { "type": "string", "default": "7d", "description": "One of 24h, 7d, 30d, 90d, 1y, all", "name": "period", "in": "query" }, { "type": "integer", "default": 1, "description": "Page of the mailbox list, 1-based", "name": "page", "in": "query" }, { "type": "integer", "default": 25, "description": "Mailboxes per page, 25 or 50", "name": "size", "in": "query" }, { "type": "string", "description": "Same search the mailbox list used", "name": "search", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/api.MailboxAnalyticsSummaryListResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/workspaces/{workspaceID}/mailboxes/{mailboxID}/analytics/activity": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Headline tiles and email-activity chart for one mailbox detail page", "produces": [ "application/json" ], "tags": [ "Mailboxes" ], "summary": "Get mailbox activity", "parameters": [ { "type": "string", "description": "Workspace ID", "name": "workspaceID", "in": "path", "required": true }, { "type": "string", "description": "Mailbox ID", "name": "mailboxID", "in": "path", "required": true }, { "type": "string", "default": "7d", "description": "One of 24h, 7d, 30d, 90d, 1y, all", "name": "period", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/api.MailboxActivityResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/workspaces/{workspaceID}/mailboxes/{mailboxID}/analytics/recipients": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Most-contacted recipients and top recipient domains for one mailbox", "produces": [ "application/json" ], "tags": [ "Mailboxes" ], "summary": "Get mailbox recipients breakdown", "parameters": [ { "type": "string", "description": "Workspace ID", "name": "workspaceID", "in": "path", "required": true }, { "type": "string", "description": "Mailbox ID", "name": "mailboxID", "in": "path", "required": true }, { "type": "string", "default": "7d", "description": "One of 24h, 7d, 30d, 90d, 1y, all", "name": "period", "in": "query" }, { "type": "integer", "default": 0, "description": "Most-contacted list offset", "name": "recipientsOffset", "in": "query" }, { "type": "integer", "default": 10, "description": "Most-contacted rows per page, max 50", "name": "recipientsLimit", "in": "query" }, { "type": "integer", "default": 10, "description": "Top domains to return, max 50", "name": "domainsLimit", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/api.MailboxRecipientsResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "definitions": { "api.ActivityBucketResponse": { "description": "One daily bucket of the email-activity chart", "type": "object", "properties": { "date": { "type": "string", "example": "2026-08-20" }, "received": { "type": "integer", "example": 42 }, "sent": { "type": "integer", "example": 18 } } }, "api.ActivityChartResponse": { "description": "Email activity chart data", "type": "object", "properties": { "buckets": { "type": "array", "items": { "$ref": "#/definitions/api.ActivityBucketResponse" } }, "totalMessages": { "type": "integer", "example": 440 } } }, "api.ActivityDomainResponse": { "description": "Domain info embedded in the activity response", "type": "object", "properties": { "domain": { "type": "string", "example": "example.com" }, "id": { "type": "string", "example": "dom_abc123" }, "status": { "type": "string", "example": "active" } } }, "api.ActivityMailboxResponse": { "description": "Mailbox info embedded in the activity response", "type": "object", "properties": { "email": { "type": "string", "example": "john.doe@example.com" }, "firstName": { "type": "string", "example": "John" }, "id": { "type": "string", "example": "mb_abc123" }, "lastName": { "type": "string", "example": "Doe" }, "status": { "type": "string", "example": "active" } } }, "api.ActivityTilesResponse": { "description": "Headline counters for the mailbox detail page", "type": "object", "properties": { "emailsReceived": { "type": "integer", "example": 125 }, "emailsSent": { "type": "integer", "example": 316 }, "replyRate": { "type": "number", "example": 39.56 } } }, "api.AdjustMailboxTopupAmountRequest": { "type": "object", "properties": { "amount": { "type": "integer" } } }, "api.AnalyticsPeriodResponse": { "description": "Period window used to build the response", "type": "object", "properties": { "dataAvailableFrom": { "type": "string", "example": "2024-01-01T00:00:00Z" }, "days": { "type": "integer", "example": 7 }, "key": { "type": "string", "example": "7d" } } }, "api.BulkAutoRenewRequest": { "type": "object", "properties": { "domainIds": { "type": "array", "items": { "type": "string" } } } }, "api.BulkForwardMailboxesRequest": { "type": "object", "properties": { "excludedIds": { "type": "array", "items": { "type": "string" } }, "forwardingEmail": { "type": "string" }, "includedIds": { "type": "array", "items": { "type": "string" } }, "search": { "type": "string" } } }, "api.BuyDomainsRequest": { "type": "object", "properties": { "contactDetails": { "$ref": "#/definitions/api.ContactDetails" }, "domains": { "type": "array", "items": { "type": "string" } }, "workspaceId": { "type": "string" } } }, "api.BuyDomainsResponse": { "type": "object", "properties": { "domains": { "type": "array", "items": { "$ref": "#/definitions/mailforge_external-api_delivery_api.DomainResponse" } } } }, "api.ContactDetails": { "type": "object", "properties": { "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "dmarcEmail": { "type": "string" }, "email": { "type": "string" }, "extra": { "description": "Extra holds TLD-specific Enom extended attributes (e.g. eu_whoispolicy for .eu).\nOptional overall; required keys depend on the TLDs being purchased — discover via GET /public/domains/extra-fields.", "type": "object", "additionalProperties": { "type": "string" } }, "firstName": { "type": "string" }, "forwardToDomain": { "type": "string" }, "jobTitle": { "type": "string" }, "lastName": { "type": "string" }, "organization": { "type": "string" }, "phone": { "type": "string" }, "postalCode": { "type": "string" }, "province": { "type": "string" } } }, "api.ContactedRowResponse": { "description": "One recipient row in the most-contacted list", "type": "object", "properties": { "contacted": { "type": "integer", "example": 12 }, "contactedPct": { "type": "number", "example": 3.79 }, "email": { "type": "string", "example": "jane@acme.com" }, "lastSent": { "type": "string", "example": "2026-08-26T11:00:00Z" } } }, "api.CreateAPIKeyRequest": { "type": "object", "properties": { "name": { "type": "string" } } }, "api.CreateAPIKeyResponse": { "type": "object", "properties": { "accountId": { "type": "string" }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "isActive": { "type": "boolean" }, "key": { "description": "raw key, shown once", "type": "string" }, "name": { "type": "string" }, "updatedAt": { "type": "string" } } }, "api.CreateDomainTransferRequest": { "type": "object", "properties": { "dmarcEmail": { "type": "string" }, "domains": { "type": "array", "items": { "type": "string" } }, "forwardToDomain": { "type": "string" }, "workspaceId": { "type": "string" } } }, "api.DomainRecordResponse": { "type": "object", "properties": { "editable": { "type": "boolean" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } } }, "api.ExternalBuyPreWarmedDomainsResponse": { "type": "object", "properties": { "domains": { "type": "array", "items": { "$ref": "#/definitions/mailforge_external-api_delivery_api.DomainResponse" } }, "invoice": { "$ref": "#/definitions/api.PurchaseInvoiceResponse" }, "mailboxes": { "type": "array", "items": { "$ref": "#/definitions/mailforge_external-api_delivery_api.MailboxResponse" } }, "setup": { "$ref": "#/definitions/api.ExternalSetupResponse" }, "workspaceId": { "type": "string" } } }, "api.ExternalGetPreWarmedDomainsListResponse": { "type": "object", "properties": { "domains": { "type": "array", "items": { "$ref": "#/definitions/api.GetAvailablePreWarmedMailboxesResponse" } }, "pagination": { "$ref": "#/definitions/api.ExternalPreWarmedDomainsPagination" } } }, "api.ExternalPreWarmedDomainsPagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } }, "api.ExternalPurchasePreWarmedDomainsRequest": { "type": "object", "properties": { "dmarcEmail": { "type": "string" }, "domainIds": { "type": "array", "items": { "type": "string" } }, "forwardToDomain": { "type": "string" }, "workspaceId": { "type": "string" } } }, "api.ExternalSetupResponse": { "type": "object", "properties": { "dmarcEmail": { "type": "string" }, "forwardToDomain": { "type": "string" }, "id": { "type": "string" }, "status": { "type": "string" }, "workspaceId": { "type": "string" } } }, "api.ExtraDomainFieldOptionResponse": { "type": "object", "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } } }, "api.ExtraDomainFieldResponse": { "type": "object", "properties": { "description": { "type": "string" }, "name": { "type": "string", "example": "eu_whoispolicy" }, "options": { "type": "array", "items": { "$ref": "#/definitions/api.ExtraDomainFieldOptionResponse" } } } }, "api.GetAvailablePreWarmedMailboxesResponse": { "type": "object", "properties": { "domain": { "type": "string" }, "id": { "type": "string" }, "mailboxes": { "type": "array", "items": { "$ref": "#/definitions/api.PreWarmedMailbox" } }, "price": { "type": "number" } } }, "api.HTTPError": { "type": "object", "properties": { "code": { "type": "integer" }, "message": {} } }, "api.MailboxActivityResponse": { "description": "Mailbox activity detail page response", "type": "object", "properties": { "degraded": { "type": "array", "items": { "type": "string" } }, "domain": { "$ref": "#/definitions/api.ActivityDomainResponse" }, "emailActivity": { "$ref": "#/definitions/api.ActivityChartResponse" }, "mailbox": { "$ref": "#/definitions/api.ActivityMailboxResponse" }, "period": { "$ref": "#/definitions/api.AnalyticsPeriodResponse" }, "tiles": { "$ref": "#/definitions/api.ActivityTilesResponse" } } }, "api.MailboxAnalyticsSummaryListResponse": { "description": "Mailbox analytics summary for a list of mailboxes", "type": "object", "properties": { "degraded": { "type": "array", "items": { "type": "string" } }, "mailboxes": { "type": "array", "items": { "$ref": "#/definitions/api.MailboxSummaryResponse" } }, "period": { "$ref": "#/definitions/api.AnalyticsPeriodResponse" } } }, "api.MailboxCredentials": { "type": "object", "properties": { "imapHost": { "type": "string", "example": "imap.server.com" }, "imapPassword": { "type": "string", "example": "password" }, "imapPort": { "type": "integer", "example": 993 }, "imapUsername": { "type": "string", "example": "user@example.com" }, "smtpHost": { "type": "string", "example": "smtp.server.com" }, "smtpPassword": { "type": "string", "example": "password" }, "smtpPort": { "type": "integer", "example": 587 }, "smtpUsername": { "type": "string", "example": "user@example.com" } } }, "api.MailboxRecipientsResponse": { "description": "Mailbox recipients breakdown response", "type": "object", "properties": { "degraded": { "type": "array", "items": { "type": "string" } }, "mostContacted": { "$ref": "#/definitions/api.MostContactedResponse" }, "period": { "$ref": "#/definitions/api.AnalyticsPeriodResponse" }, "topRecipientDomains": { "type": "array", "items": { "$ref": "#/definitions/api.RecipientDomainRowResponse" } } } }, "api.MailboxSummaryResponse": { "description": "Per-mailbox analytics row for the mailbox list page", "type": "object", "properties": { "mailboxId": { "type": "string", "example": "mb_abc123" }, "received": { "type": "integer", "example": 125 }, "replyRate": { "type": "number", "example": 39.56 }, "sent": { "type": "integer", "example": 316 }, "status": { "type": "string", "example": "ok" }, "trend": { "type": "array", "items": { "$ref": "#/definitions/api.TrendPointResponse" } } } }, "api.MostContactedResponse": { "description": "Paginated list of most-contacted recipients", "type": "object", "properties": { "pagination": { "$ref": "#/definitions/api.OffsetPageResponse" }, "rows": { "type": "array", "items": { "$ref": "#/definitions/api.ContactedRowResponse" } }, "truncated": { "type": "boolean", "example": false } } }, "api.OffsetPageResponse": { "description": "Offset-based pagination metadata", "type": "object", "properties": { "hasMore": { "type": "boolean", "example": true }, "limit": { "type": "integer", "example": 10 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 87 } } }, "api.PreWarmedMailbox": { "type": "object", "properties": { "email": { "type": "string" }, "fullName": { "type": "string" } } }, "api.PurchaseDomainMaskingRequest": { "type": "object", "properties": { "domainIds": { "type": "array", "items": { "type": "string" } }, "isYearly": { "type": "boolean" }, "purchaseMasking": { "type": "boolean" } } }, "api.PurchaseInvoiceResponse": { "type": "object", "properties": { "amountPaid": { "type": "integer" }, "creditsApplied": { "type": "integer" }, "id": { "type": "string" }, "paidAt": { "type": "string" }, "subTotal": { "type": "integer" }, "total": { "type": "integer" } } }, "api.RecipientDomainRowResponse": { "description": "Sends aggregated by recipient domain", "type": "object", "properties": { "domain": { "type": "string", "example": "acme.com" }, "sentTo": { "type": "integer", "example": 45 }, "sentToPct": { "type": "number", "example": 14.24 } } }, "api.SubscriptionBalanceError": { "type": "object", "properties": { "code": { "type": "string", "example": "unpaid_subscription_balance" }, "message": { "type": "string" } } }, "api.SuggestAlternativeDomainsRequest": { "type": "object", "properties": { "count": { "type": "integer" }, "inputSld": { "type": "string" }, "outputTld": { "type": "string" } } }, "api.TrendPointResponse": { "description": "One daily point of the mailbox activity sparkline", "type": "object", "properties": { "date": { "type": "string", "example": "2026-08-20" }, "received": { "type": "integer", "example": 42 }, "sent": { "type": "integer", "example": 18 } } }, "api.UpdateAPIKeyRequest": { "type": "object", "properties": { "isActive": { "type": "boolean" } } }, "api.UpdateDomainDNSRequest": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/definitions/models.DomainRecord" } } } }, "api.UpdateWorkspaceRequest": { "type": "object", "properties": { "name": { "type": "string" } } }, "api.WorkspaceResponse": { "type": "object", "properties": { "accountId": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "http.isSpamResponse": { "type": "object", "properties": { "is_spam": { "type": "boolean" } } }, "mailforge_external-api_delivery_api.APIKeyResponse": { "type": "object", "properties": { "accountId": { "type": "string" }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": "string" }, "name": { "type": "string" }, "updatedAt": { "type": "string" } } }, "mailforge_external-api_delivery_api.BuyMailboxesRequest": { "type": "object", "properties": { "mailboxes": { "type": "array", "items": { "$ref": "#/definitions/models.CreateMailboxPayload" } } } }, "mailforge_external-api_delivery_api.BuyMailboxesResponse": { "type": "object", "properties": { "mailboxes": { "type": "array", "items": { "$ref": "#/definitions/mailforge_external-api_delivery_api.MailboxResponse" } } } }, "mailforge_external-api_delivery_api.CheckDomainAvailabilityBulkRequest": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "string" } } } }, "mailforge_external-api_delivery_api.CreateDomainTransferResponse": { "type": "object", "properties": { "allDomainsAlreadyInWorkspace": { "type": "boolean" }, "domains": { "type": "array", "items": { "$ref": "#/definitions/mailforge_external-api_delivery_api.DomainResponse" } }, "invoice": { "$ref": "#/definitions/api.PurchaseInvoiceResponse" } } }, "mailforge_external-api_delivery_api.CreateWorkspaceRequest": { "type": "object", "properties": { "name": { "type": "string" } } }, "mailforge_external-api_delivery_api.DomainAvailabilityResponse": { "type": "object", "properties": { "available": { "type": "boolean" }, "domain": { "type": "string" }, "price": { "type": "number" } } }, "mailforge_external-api_delivery_api.DomainMaskingResponse": { "type": "object", "properties": { "destinationDomain": { "type": "string" }, "forwardingStatus": { "$ref": "#/definitions/models.ForwardingStatus" }, "ip": { "type": "string" }, "masking": { "type": "boolean" }, "routeInServer": { "type": "boolean" }, "sourceDomain": { "type": "string" } } }, "mailforge_external-api_delivery_api.DomainResponse": { "type": "object", "properties": { "autoRenewFailedReason": { "type": "string" }, "autoRenewLastProcessedExpiration": { "type": "string" }, "autoRenewProcessedAt": { "type": "string" }, "autoRenewStatus": { "$ref": "#/definitions/models.DomainAutoRenewStatus" }, "createdAt": { "type": "string" }, "dmarcEmail": { "type": "string" }, "expiresAt": { "type": "string" }, "failedReason": { "type": "string" }, "forwardToDomain": { "type": "string" }, "id": { "type": "string" }, "isTransferred": { "type": "boolean" }, "mailServerId": { "type": "integer" }, "nameservers": { "type": "array", "items": { "type": "string" } }, "priceCents": { "type": "integer" }, "setupId": { "type": "string" }, "sld": { "type": "string" }, "status": { "$ref": "#/definitions/models.DomainStatus" }, "tld": { "type": "string" }, "type": { "$ref": "#/definitions/models.DomainType" }, "updatedAt": { "type": "string" }, "workspaceId": { "type": "string" } } }, "mailforge_external-api_delivery_api.MailboxResponse": { "type": "object", "properties": { "createdAt": { "type": "string" }, "credentials": { "$ref": "#/definitions/api.MailboxCredentials" }, "domain": { "type": "string" }, "domainId": { "type": "string" }, "email": { "type": "string" }, "failedReason": { "type": "string" }, "firstName": { "type": "string" }, "forwardingEmail": { "type": "string" }, "forwardingStatus": { "$ref": "#/definitions/models.ForwardingStatus" }, "id": { "type": "string" }, "isPrewarmed": { "type": "boolean" }, "isTransferred": { "type": "boolean" }, "lastName": { "type": "string" }, "nameservers": { "type": "array", "items": { "type": "string" } }, "signature": { "type": "string" }, "status": { "$ref": "#/definitions/models.MailboxStatus" }, "updatedAt": { "type": "string" }, "username": { "type": "string" }, "workspaceId": { "type": "string" } } }, "mailforge_external-api_delivery_api.UpdateDomainForwardsRequest": { "type": "object", "properties": { "domainId": { "type": "string" }, "domainMasking": { "type": "boolean" }, "forwardToDomain": { "type": "string" } } }, "models.CNameRecord": { "type": "object", "properties": { "address": { "type": "string" }, "hostName": { "type": "string" } } }, "models.CreateMailboxPayload": { "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "forwardingEmail": { "type": "string" }, "lastName": { "type": "string" }, "signature": { "type": "string" } } }, "models.DNSUpdatePayload": { "type": "object", "properties": { "cnameRecords": { "type": "array", "items": { "$ref": "#/definitions/models.CNameRecord" } }, "dmarcEmail": { "type": "string" }, "dmarcPolicy": { "type": "string" }, "domainRecords": { "type": "array", "items": { "$ref": "#/definitions/models.DomainRecord" } }, "domains": { "type": "array", "items": { "type": "string" } }, "forwardToDomain": { "type": "string" }, "removeENOMRecords": { "type": "boolean" }, "replacementDKIMRecord": { "$ref": "#/definitions/models.DomainRecord" }, "replacementMXRecord": { "$ref": "#/definitions/models.DomainRecord" }, "replacementSPFRecord": { "$ref": "#/definitions/models.DomainRecord" } } }, "models.DomainAutoRenewStatus": { "type": "string", "enum": [ "disabled", "enabled", "failed" ], "x-enum-varnames": [ "DomainAutoRenewStatusDisabled", "DomainAutoRenewStatusEnabled", "DomainAutoRenewStatusFailed" ] }, "models.DomainRecord": { "type": "object", "properties": { "editable": { "type": "boolean" }, "name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } } }, "models.DomainStatus": { "type": "string", "enum": [ "draft", "active", "pending", "failed", "expired", "warning", "scheduled_for_deletion", "not_paid" ], "x-enum-varnames": [ "DomainStatusDraft", "DomainStatusActive", "DomainStatusPending", "DomainStatusFailed", "DomainStatusExpired", "DomainStatusWarning", "DomainStatusScheduledForDeletion", "DomainStatusNotPaid" ] }, "models.DomainType": { "type": "string", "enum": [ "v2" ], "x-enum-varnames": [ "DomainTypeV2" ] }, "models.ForwardingStatus": { "type": "string", "enum": [ "pending", "active", "failed" ], "x-enum-varnames": [ "ForwardingStatusPending", "ForwardingStatusActive", "ForwardingStatusFailed" ] }, "models.MailboxStatus": { "type": "string", "enum": [ "draft", "active", "pending", "processing", "failed", "scheduled_for_deletion", "deleting" ], "x-enum-varnames": [ "MailboxStatusDraft", "MailboxStatusActive", "MailboxStatusPending", "MailboxStatusProcessing", "MailboxStatusFailed", "MailboxStatusScheduledForDeletion", "MailboxStatusDeleting" ] }, "models.UpdateMailboxPayload": { "type": "object", "properties": { "firstName": { "type": "string" }, "forwardingEmail": { "type": "string" }, "lastName": { "type": "string" }, "password": { "type": "string" }, "signature": { "type": "string" }, "username": { "type": "string" } } }, "spamcheck.CheckRequest": { "type": "object", "properties": { "body_html": { "type": "string" }, "body_plain": { "type": "string" }, "subject": { "type": "string" } } } }, "securityDefinitions": { "ApiKeyAuth": { "type": "apiKey", "name": "Authorization", "in": "header" } } }