{ "openapi": "3.0.3", "info": { "title": "HideMail App API", "description": "", "version": "1.0.0" }, "servers": [ { "url": "https://hidemail.app" } ], "tags": [ { "name": "Endpoints", "description": "" } ], "components": { "securitySchemes": { "default": { "type": "http", "scheme": "bearer", "description": "You can retrieve your token by visiting your dashboard, find in menu API tokens and create a new one." } } }, "security": [ { "default": [] } ], "paths": { "/api/v1/sanctum/token": { "post": { "summary": "Create a token.", "operationId": "createAToken", "description": "This endpoint lets you create a permanent token. When the account has\ntwo-factor authentication enabled and the client sends\n`two_factor_supported: true`, it returns `409` with a challenge to\nexchange at `POST /api/v1/sanctum/token/two-factor`.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "description": "Two-factor authentication off", "type": "object", "example": { "token": "1a2b3c..." }, "properties": { "token": { "type": "string", "example": "1a2b3c..." } } }, { "description": "Legacy client during the grace window", "type": "object", "example": { "token": "1a2b3c...", "warnings": [ { "code": "two_factor_client_upgrade_required", "message": "This app cannot ask for your two-factor authentication code. Update it before Oct 12, 2026, when signing in from this version will stop working.", "enforced_at": "2026-10-12" } ] }, "properties": { "token": { "type": "string", "example": "1a2b3c..." }, "warnings": { "type": "array", "example": [ { "code": "two_factor_client_upgrade_required", "message": "This app cannot ask for your two-factor authentication code. Update it before Oct 12, 2026, when signing in from this version will stop working.", "enforced_at": "2026-10-12" } ], "items": { "type": "object", "properties": { "code": { "type": "string", "example": "two_factor_client_upgrade_required" }, "message": { "type": "string", "example": "This app cannot ask for your two-factor authentication code. Update it before Oct 12, 2026, when signing in from this version will stop working." }, "enforced_at": { "type": "string", "example": "2026-10-12" } } } } } } ] } } } }, "403": { "description": "Legacy client after the cutover", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "two_factor_client_upgrade_required", "message": "Two-factor authentication is enabled on this account and this app cannot ask for your code. Update the app to sign in." }, "properties": { "error": { "type": "string", "example": "two_factor_client_upgrade_required" }, "message": { "type": "string", "example": "Two-factor authentication is enabled on this account and this app cannot ask for your code. Update the app to sign in." } } } } } }, "409": { "description": "Two-factor challenge required", "content": { "application/json": { "schema": { "type": "object", "example": { "two_factor_required": true, "challenge": "3f9c...64 chars", "expires_in": 300, "methods": [ "totp", "recovery_code" ] }, "properties": { "two_factor_required": { "type": "boolean", "example": true }, "challenge": { "type": "string", "example": "3f9c...64 chars" }, "expires_in": { "type": "integer", "example": 300 }, "methods": { "type": "array", "example": [ "totp", "recovery_code" ], "items": { "type": "string" } } } } } } }, "422": { "description": "Wrong credentials", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "The provided credentials are incorrect.", "errors": { "email": [ "The provided credentials are incorrect." ] } }, "properties": { "message": { "type": "string", "example": "The provided credentials are incorrect." }, "errors": { "type": "object", "properties": { "email": { "type": "array", "example": [ "The provided credentials are incorrect." ], "items": { "type": "string" } } } } } } } } } }, "tags": [ "Endpoints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email.", "example": "hi@example.com" }, "password": { "type": "string", "description": "Password.", "example": "password" }, "device_name": { "type": "string", "description": "Device Name.", "example": "Raycast" }, "two_factor_supported": { "type": "boolean", "description": "Declares that the client can complete a two-factor challenge. Defaults to false.", "example": true } }, "required": [ "email", "password", "device_name" ] } } } }, "security": [] } }, "/api/v1/sanctum/token/two-factor": { "post": { "summary": "Complete a two-factor challenge.", "operationId": "completeATwoFactorChallenge", "description": "Exchanges the `challenge` returned by a `409` from `POST /api/v1/sanctum/token`\nfor a permanent token. Send either a six-digit `code` from the authenticator\napp or one `recovery_code`. A challenge is single-use, expires after five\nminutes, and is burned after five wrong codes.\n\nThe `two_factor_too_many_attempts` 429 below burns the challenge, so the\nclient must sign in with the password again to get a new one. This is\ndistinct from the route's own rate limiter, whose 429 has a plain\n`{\"message\", \"status\": 429}` body (see `App\\Exceptions\\Handler::handleApiException`)\nand does not burn the challenge.", "parameters": [], "responses": { "200": { "description": "Verified", "content": { "application/json": { "schema": { "type": "object", "example": { "token": "1a2b3c..." }, "properties": { "token": { "type": "string", "example": "1a2b3c..." } } } } } }, "410": { "description": "Challenge unknown, expired or burned", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "two_factor_challenge_expired", "message": "This sign-in attempt has expired. Sign in with your password again." }, "properties": { "error": { "type": "string", "example": "two_factor_challenge_expired" }, "message": { "type": "string", "example": "This sign-in attempt has expired. Sign in with your password again." } } } } } }, "422": { "description": "Wrong code", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "The provided two factor authentication code was invalid.", "errors": { "code": [ "The provided two factor authentication code was invalid." ] }, "attempts_remaining": 3 }, "properties": { "message": { "type": "string", "example": "The provided two factor authentication code was invalid." }, "errors": { "type": "object", "properties": { "code": { "type": "array", "example": [ "The provided two factor authentication code was invalid." ], "items": { "type": "string" } } } }, "attempts_remaining": { "type": "integer", "example": 3 } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "oneOf": [ { "description": "Too many wrong codes for this account", "type": "object", "example": { "error": "two_factor_too_many_attempts", "message": "Too many incorrect codes. Try again later.", "retry_after": 900 }, "properties": { "error": { "type": "string", "example": "two_factor_too_many_attempts" }, "message": { "type": "string", "example": "Too many incorrect codes. Try again later." }, "retry_after": { "type": "integer", "example": 900 } } }, { "description": "Another request for this challenge or account is in flight", "type": "object", "example": { "error": "two_factor_busy", "message": "Another sign-in attempt is in progress. Try again in a moment." }, "properties": { "error": { "type": "string", "example": "two_factor_busy" }, "message": { "type": "string", "example": "Another sign-in attempt is in progress. Try again in a moment." } } } ] } } } } }, "tags": [ "Endpoints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge": { "type": "string", "description": "The challenge from the 409 response.", "example": "3f9c..." }, "device_name": { "type": "string", "description": "Device Name. This is validated but not used to\n name the token: the device name recorded on the token is the one sent with the original\n `POST /api/v1/sanctum/token` request that issued this challenge.", "example": "Raycast" }, "code": { "type": "string", "description": "Six-digit authenticator code. Required unless recovery_code is present.", "example": "123456", "nullable": true }, "recovery_code": { "type": "string", "description": "A recovery code. Required unless code is present.", "example": "abcde12345-fghij67890", "nullable": true } }, "required": [ "challenge", "device_name" ] } } } }, "security": [] } }, "/api/user": { "get": { "summary": "Get Api User", "operationId": "getApiUser", "description": "Returns the email address of the token owner. Use it to check that a token works.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "email": "you@example.com" }, "properties": { "email": { "type": "string", "example": "you@example.com" } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Not authenticated" }, "properties": { "message": { "type": "string", "example": "Not authenticated" } } } } } } }, "tags": [ "Endpoints" ] } }, "/api/v1/email/create": { "post": { "summary": "Post Api V1 Email Create", "operationId": "postApiV1EmailCreate", "description": "Creates a new alias. Pass `domain` to create it on one of your alias domains (see /api/v1/alias-domains); when it is empty, your default alias domain is used. Any other domain is refused with 422.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "status": "success", "email": "k3j9x@hidemail.app" }, "properties": { "status": { "type": "string", "example": "success" }, "email": { "type": "string", "example": "k3j9x@hidemail.app" } } } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "status": "success", "message": "You have reached the limit of emails.", "messageLink": "https://hidemail.app/plans", "messageLinkTitle": "Please subscribe on web-site to continue.", "showSubscribeButton": true }, "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "You have reached the limit of emails." }, "messageLink": { "type": "string", "example": "https://hidemail.app/plans" }, "messageLinkTitle": { "type": "string", "example": "Please subscribe on web-site to continue." }, "showSubscribeButton": { "type": "boolean", "example": true } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "status": "error", "message": "This domain is not one of your alias domains. Use one of: hidemail.app" }, "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "This domain is not one of your alias domains. Use one of: hidemail.app" } } } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "status": "error", "message": "Too many requests" }, "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Too many requests" } } } } } } }, "tags": [ "Endpoints" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Note for the alias, at most 200 characters.", "example": "My shopping account" }, "domain": { "type": "string", "description": "One of your alias domains. Empty: your default alias domain.", "example": "hidemail.app" } } } } } } } }, "/api/v1/domain-options": { "get": { "summary": "Get Api V1 Domain Options", "operationId": "getApiV1DomainOptions", "description": "The domains you can create aliases on, in the format alias-generator clients such as Bitwarden read: every usable domain, the built-in shared domain, your default domain and the alias format. /api/v1/alias-domains returns the same domains with more detail.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ "hidemail.app", "example.com" ], "sharedDomains": [ "hidemail.app" ], "defaultAliasDomain": "example.com", "defaultAliasFormat": "random_characters", "me": "you@example.com" }, "properties": { "data": { "type": "array", "example": [ "hidemail.app", "example.com" ], "items": { "type": "string" } }, "sharedDomains": { "type": "array", "example": [ "hidemail.app" ], "items": { "type": "string" } }, "defaultAliasDomain": { "type": "string", "example": "example.com" }, "defaultAliasFormat": { "type": "string", "example": "random_characters" }, "me": { "type": "string", "example": "you@example.com" } } } } } } }, "tags": [ "Endpoints" ] } }, "/api/v1/aliases": { "post": { "summary": "Create a new email alias.", "operationId": "createANewEmailAlias", "description": "This endpoint lets you create a new alias. Pass `domain` to create it on one of your alias domains (see /api/v1/alias-domains); when it is empty, your default alias domain is used. Any other domain is refused with 422.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "email": "alias@hidemail.app", "note": "My shopping account", "is_active": true, "created_at": "2024-01-28T15:03:09.000000Z", "updated_at": "2024-01-28T15:03:09.000000Z", "total_forwarded": 0, "total_blocked": 0 } }, "properties": { "data": { "type": "object", "properties": { "email": { "type": "string", "example": "alias@hidemail.app" }, "note": { "type": "string", "example": "My shopping account" }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "example": "2024-01-28T15:03:09.000000Z" }, "updated_at": { "type": "string", "example": "2024-01-28T15:03:09.000000Z" }, "total_forwarded": { "type": "integer", "example": 0 }, "total_blocked": { "type": "integer", "example": 0 } } } } } } } } }, "tags": [ "Endpoints" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Note for the alias, at most 200 characters.", "example": "My shopping account" }, "domain": { "type": "string", "description": "One of your alias domains. Empty: your default alias domain.", "example": "hidemail.app" } } } } } } }, "patch": { "summary": "Update an email alias note.", "operationId": "updateAnEmailAliasNote", "description": "This endpoint allows you to update the note for a specific email alias.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "email": "alias@hidemail.app", "note": "My shopping account", "is_active": true, "created_at": "2024-01-28T15:03:09.000000Z", "updated_at": "2024-01-28T15:03:09.000000Z", "total_forwarded": 0, "total_blocked": 0 } }, "properties": { "data": { "type": "object", "properties": { "email": { "type": "string", "example": "alias@hidemail.app" }, "note": { "type": "string", "example": "My shopping account" }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "example": "2024-01-28T15:03:09.000000Z" }, "updated_at": { "type": "string", "example": "2024-01-28T15:03:09.000000Z" }, "total_forwarded": { "type": "integer", "example": 0 }, "total_blocked": { "type": "integer", "example": 0 } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Email alias not found" }, "properties": { "message": { "type": "string", "example": "Email alias not found" } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "The note field is required.", "errors": { "note": [ "The note field is required." ] } }, "properties": { "message": { "type": "string", "example": "The note field is required." }, "errors": { "type": "object", "properties": { "note": { "type": "array", "example": [ "The note field is required." ], "items": { "type": "string" } } } } } } } } } }, "tags": [ "Endpoints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "description": "The new note for the alias. Max 255 characters. Must not be greater than 255 characters.", "example": "My shopping account" }, "email": { "type": "string", "description": "The email alias to update. Must be a valid email address.", "example": "alias@hidemail.app" } }, "required": [ "note", "email" ] } } } } }, "get": { "summary": "Get all aliases.", "operationId": "getAllAliases", "description": "This endpoint lets you get all your aliases.", "parameters": [ { "in": "query", "name": "page", "description": "Pagination options.", "example": null, "required": false, "schema": { "type": "object", "description": "Pagination options.", "example": null, "properties": {}, "nullable": true } }, { "in": "query", "name": "page.number", "description": "The page to return. Must be at least 1.", "example": 1, "required": false, "schema": { "type": "integer", "description": "The page to return. Must be at least 1.", "example": 1, "nullable": true } }, { "in": "query", "name": "page.size", "description": "Aliases per page, up to 100. Must not be greater than 100. Must be at least 1.", "example": 100, "required": false, "schema": { "type": "integer", "description": "Aliases per page, up to 100. Must not be greater than 100. Must be at least 1.", "example": 100, "nullable": true } }, { "in": "query", "name": "filter", "description": "Filters to apply.", "example": null, "required": false, "schema": { "type": "object", "description": "Filters to apply.", "example": null, "properties": {}, "nullable": true } }, { "in": "query", "name": "search", "description": "Search aliases by email or note, 3 to 50 characters. Must not be greater than 50 characters. Must be at least 3 characters.", "example": "shop", "required": false, "schema": { "type": "string", "description": "Search aliases by email or note, 3 to 50 characters. Must not be greater than 50 characters. Must be at least 3 characters.", "example": "shop", "nullable": true } }, { "in": "query", "name": "filter.is_active", "description": "Return only active (1) or inactive (0) aliases. Must not be greater than 1. Must be at least 0.", "example": 1, "required": false, "schema": { "type": "integer", "description": "Return only active (1) or inactive (0) aliases. Must not be greater than 1. Must be at least 0.", "example": 1, "nullable": true } }, { "in": "query", "name": "sort", "description": "Sort field. Prefix with - for descending order. Must not be greater than 50 characters. Must be at least 3 characters.", "example": "-created_at", "required": false, "schema": { "type": "string", "description": "Sort field. Prefix with - for descending order. Must not be greater than 50 characters. Must be at least 3 characters.", "example": "-created_at", "enum": [ "email", "is_active", "created_at", "updated_at", "total_blocked", "total_forwarded", "-total_blocked", "-total_forwarded", "-email", "-is_active", "-created_at", "-updated_at" ], "nullable": true } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "email": "gbailey@hidemail.app", "is_active": true, "note": null, "total_forwarded": 0, "total_blocked": 0, "created_at": "2026-11-03 15:24:41", "updated_at": "2026-11-03 15:24:41" }, { "email": "cecil42@hidemail.app", "is_active": true, "note": null, "total_forwarded": 0, "total_blocked": 0, "created_at": "2026-11-03 15:24:41", "updated_at": "2026-11-03 15:24:41" } ] }, "properties": { "data": { "type": "array", "example": [ { "email": "gbailey@hidemail.app", "is_active": true, "note": null, "total_forwarded": 0, "total_blocked": 0, "created_at": "2026-11-03 15:24:41", "updated_at": "2026-11-03 15:24:41" }, { "email": "cecil42@hidemail.app", "is_active": true, "note": null, "total_forwarded": 0, "total_blocked": 0, "created_at": "2026-11-03 15:24:41", "updated_at": "2026-11-03 15:24:41" } ], "items": { "type": "object", "properties": { "email": { "type": "string", "example": "gbailey@hidemail.app" }, "is_active": { "type": "boolean", "example": true }, "note": { "type": "string", "example": null, "nullable": true }, "total_forwarded": { "type": "integer", "example": 0 }, "total_blocked": { "type": "integer", "example": 0 }, "created_at": { "type": "string", "example": "2026-11-03 15:24:41" }, "updated_at": { "type": "string", "example": "2026-11-03 15:24:41" } } } } } } } } } }, "tags": [ "Endpoints" ] } }, "/api/v1/active-aliases": { "post": { "summary": "Activate an alias.", "operationId": "activateAnAlias", "description": "This endpoint lets you update the status of an alias to active.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "email": "rempel.chadrick@hidemail.app", "is_active": true, "note": null, "total_forwarded": 0, "total_blocked": 0, "created_at": "2026-11-03 15:24:41", "updated_at": "2026-11-03 15:24:41" } }, "properties": { "data": { "type": "object", "properties": { "email": { "type": "string", "example": "rempel.chadrick@hidemail.app" }, "is_active": { "type": "boolean", "example": true }, "note": { "type": "string", "example": null, "nullable": true }, "total_forwarded": { "type": "integer", "example": 0 }, "total_blocked": { "type": "integer", "example": 0 }, "created_at": { "type": "string", "example": "2026-11-03 15:24:41" }, "updated_at": { "type": "string", "example": "2026-11-03 15:24:41" } } } } } } } } }, "tags": [ "Endpoints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The email you want to activate", "example": "gbailey@example.net" } }, "required": [ "email" ] } } } } } }, "/api/v1/delete-aliases": { "delete": { "summary": "Deactivate an alias.", "operationId": "deactivateAnAlias", "description": "This endpoint lets you update the status of an alias to in active.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "email": "jdach@hidemail.app", "is_active": true, "note": null, "total_forwarded": 0, "total_blocked": 0, "created_at": "2026-11-03 15:24:41", "updated_at": "2026-11-03 15:24:41" } }, "properties": { "data": { "type": "object", "properties": { "email": { "type": "string", "example": "jdach@hidemail.app" }, "is_active": { "type": "boolean", "example": true }, "note": { "type": "string", "example": null, "nullable": true }, "total_forwarded": { "type": "integer", "example": 0 }, "total_blocked": { "type": "integer", "example": 0 }, "created_at": { "type": "string", "example": "2026-11-03 15:24:41" }, "updated_at": { "type": "string", "example": "2026-11-03 15:24:41" } } } } } } } } }, "tags": [ "Endpoints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The email you want to deactivate", "example": "gbailey@example.net" } }, "required": [ "email" ] } } } } } }, "/api/v1/subscribe": { "post": { "summary": "Set a webhook URL.", "operationId": "setAWebhookURL", "description": "This endpoint lets you create a webhook URL. After you get email on any of your aliases we will send all data to this URL. You can do automation with this data and create your own integrations. The URL must use https, and the account owner is emailed whenever the webhook changes.", "parameters": [], "responses": { "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Not authenticated" }, "properties": { "message": { "type": "string", "example": "Not authenticated" } } } } } } }, "tags": [ "Endpoints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hookUrl": { "type": "string", "description": "An https URL that receives a copy of every incoming email.", "example": "https://hooks.slack.com/services/T0000/B0000/XXXXXXXX" } }, "required": [ "hookUrl" ] } } } } } }, "/api/v1/unsubscribe": { "delete": { "summary": "Remove a webhook URL.", "operationId": "removeAWebhookURL", "description": "This endpoint lets you remove a webhook URL. The account owner is emailed when a webhook is removed.", "parameters": [], "responses": { "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Not authenticated" }, "properties": { "message": { "type": "string", "example": "Not authenticated" } } } } } } }, "tags": [ "Endpoints" ] } }, "/api/v1/alias-domains": { "get": { "summary": "List alias domains.", "operationId": "listAliasDomains", "description": "The domains new aliases can be created on: the built-in HideMail domain and your custom domains that can receive mail. The one marked is_default is used for new aliases.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "domain": "relay.hidemail.app", "is_custom": false, "is_default": false }, { "domain": "example.com", "is_custom": true, "is_default": true } ] }, "properties": { "data": { "type": "array", "example": [ { "domain": "relay.hidemail.app", "is_custom": false, "is_default": false }, { "domain": "example.com", "is_custom": true, "is_default": true } ], "items": { "type": "object", "properties": { "domain": { "type": "string", "example": "relay.hidemail.app" }, "is_custom": { "type": "boolean", "example": false }, "is_default": { "type": "boolean", "example": false } } } } } } } } } }, "tags": [ "Endpoints" ] } }, "/api/v1/default-alias-domain": { "put": { "summary": "Set the default alias domain.", "operationId": "setTheDefaultAliasDomain", "description": "New aliases are created on this domain. Use one of your custom domains that can receive mail, or the built-in HideMail domain to switch back.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "domain": "example.com" } }, "properties": { "data": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com" } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "You have no custom domain with that name." }, "properties": { "message": { "type": "string", "example": "You have no custom domain with that name." } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "This domain cannot receive mail yet. Verify its MX record first." }, "properties": { "message": { "type": "string", "example": "This domain cannot receive mail yet. Verify its MX record first." } } } } } } }, "tags": [ "Endpoints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "A domain from the alias domains list.", "example": "example.com" } }, "required": [ "domain" ] } } } } }, "delete": { "summary": "Reset the default alias domain.", "operationId": "resetTheDefaultAliasDomain", "description": "New aliases go back to the built-in HideMail domain.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "domain": "relay.hidemail.app" } }, "properties": { "data": { "type": "object", "properties": { "domain": { "type": "string", "example": "relay.hidemail.app" } } } } } } } } }, "tags": [ "Endpoints" ] } }, "/api/v1/custom-domains": { "get": { "summary": "List custom domains.", "operationId": "listCustomDomains", "description": "Your own domains added to HideMail, with their setup status (provisioning, provisioning_failed, needs_mx, ready) and whether catch-all is on.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "domain": "example.com", "status": "ready", "active": true, "catch_all": false } ] }, "properties": { "data": { "type": "array", "example": [ { "domain": "example.com", "status": "ready", "active": true, "catch_all": false } ], "items": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com" }, "status": { "type": "string", "example": "ready" }, "active": { "type": "boolean", "example": true }, "catch_all": { "type": "boolean", "example": false } } } } } } } } } }, "tags": [ "Endpoints" ] }, "post": { "summary": "Add a custom domain.", "operationId": "addACustomDomain", "description": "Publish the ownership TXT record from the setup endpoint first. Setup in the mail server then runs for a few seconds; publish the MX record and verify the domain.", "parameters": [], "responses": { "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Not authenticated" }, "properties": { "message": { "type": "string", "example": "Not authenticated" } } } } } } }, "tags": [ "Endpoints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain.", "example": "example.com" } }, "required": [ "domain" ] } } } } } }, "/api/v1/custom-domains/{domain}": { "get": { "summary": "Show a custom domain's setup.", "operationId": "showACustomDomainsSetup", "description": "The DNS records the domain needs (ownership TXT and MX), whether each is published, the MX hosts it uses now and its setup status. Works for a domain you have not added yet: its status is not_added until you add it, then provisioning, provisioning_failed, needs_mx or ready.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "domain": "example.com", "status": "needs_mx", "catch_all": false, "dns_records": [ { "type": "TXT", "name": "example.com", "value": "hidemail-verify=3f9a1c", "priority": null, "purpose": "Proves you own the domain. Publish it before adding the domain.", "found": true }, { "type": "MX", "name": "example.com", "value": "mx.postal.hidemail.app", "priority": 10, "purpose": "Delivers the domain's mail to HideMail. It must be the only MX record, or the one with the lowest priority.", "found": false } ], "current_mx_hosts": [], "replaces_other_mail_provider": false } }, "properties": { "data": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com" }, "status": { "type": "string", "example": "needs_mx" }, "catch_all": { "type": "boolean", "example": false }, "dns_records": { "type": "array", "example": [ { "type": "TXT", "name": "example.com", "value": "hidemail-verify=3f9a1c", "priority": null, "purpose": "Proves you own the domain. Publish it before adding the domain.", "found": true }, { "type": "MX", "name": "example.com", "value": "mx.postal.hidemail.app", "priority": 10, "purpose": "Delivers the domain's mail to HideMail. It must be the only MX record, or the one with the lowest priority.", "found": false } ], "items": { "type": "object", "properties": { "type": { "type": "string", "example": "TXT" }, "name": { "type": "string", "example": "example.com" }, "value": { "type": "string", "example": "hidemail-verify=3f9a1c" }, "priority": { "type": "string", "example": null, "nullable": true }, "purpose": { "type": "string", "example": "Proves you own the domain. Publish it before adding the domain." }, "found": { "type": "boolean", "example": true } } } }, "current_mx_hosts": { "type": "array", "example": [] }, "replaces_other_mail_provider": { "type": "boolean", "example": false } } } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "That is not a valid domain name." }, "properties": { "message": { "type": "string", "example": "That is not a valid domain name." } } } } } } }, "tags": [ "Endpoints" ] }, "parameters": [ { "in": "path", "name": "domain", "description": "The domain.", "example": "example.com", "required": true, "schema": { "type": "string" } } ] }, "/api/v1/custom-domains/{domain}/verification": { "post": { "summary": "Verify a custom domain.", "operationId": "verifyACustomDomain", "description": "Checks that the domain's MX record points at HideMail and starts receiving its mail.", "parameters": [], "responses": { "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Not authenticated" }, "properties": { "message": { "type": "string", "example": "Not authenticated" } } } } } } }, "tags": [ "Endpoints" ] }, "parameters": [ { "in": "path", "name": "domain", "description": "The domain.", "example": "example.com", "required": true, "schema": { "type": "string" } } ] }, "/api/v1/custom-domains/{domain}/catch-all": { "put": { "summary": "Turn catch-all on or off.", "operationId": "turnCatchAllOnOrOff", "description": "With catch-all on, mail to any address on the domain that has no alias yet creates that alias (paid plan only). With it off, such mail is dropped.", "parameters": [], "responses": { "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Not authenticated" }, "properties": { "message": { "type": "string", "example": "Not authenticated" } } } } } } }, "tags": [ "Endpoints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Turn catch-all on (true) or off (false).", "example": true } }, "required": [ "enabled" ] } } } } }, "parameters": [ { "in": "path", "name": "domain", "description": "The domain.", "example": "example.com", "required": true, "schema": { "type": "string" } } ] }, "/api/v1/delete-token": { "delete": { "summary": "Delete api token", "operationId": "deleteApiToken", "description": "This endpoint lets you remove an api token.", "parameters": [], "responses": { "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Not authenticated" }, "properties": { "message": { "type": "string", "example": "Not authenticated" } } } } } } }, "tags": [ "Endpoints" ] } } } }