Hide-My-Email.info API Documentation
All documents

Aliases, Alias Lengths, Domains, and 10-Minute Aliases

All endpoints in this document require secret: sk1_... and x-account-access-id: aid1.....

Alias Endpoints

Alias creation options

GET /api/v1/aliases/options

Returns effective alias length limits and allowed domains. This endpoint resolves the effective alias configuration for the authenticated account, including public catalog items and any user-owned overrides that the account is currently allowed to use.

Response fields

  • domains[]
  • minAliasLength
  • maxAliasLength
  • defaultAliasLength

Example

curl "http://Hide-My-Email.info/api/v1/aliases/options" -H "secret: sk1_example"

List aliases

GET /api/v1/aliases

Returns the account's regular aliases. Aliases that were deleted less than 30 days ago may still appear in account state and still forward incoming mail during that grace period.

Query parameters

  • offset - optional integer, default server value
  • take - optional integer page size

Response fields

  • items[]
  • items[].id
  • items[].aliasAddress
  • items[].forwardToEmail
  • items[].description
  • items[].isFavorite
  • items[].ignoreEmails
  • items[].allowedWebsiteOrDomain
  • items[].allowSubdomains
  • items[].outsideAllowedDomainAlertEnabled
  • items[].outsideAllowedDomainAction
  • hasMore
  • nextOffset

Example

curl "http://Hide-My-Email.info/api/v1/aliases?offset=0&take=20" -H "secret: sk1_example"

Read one alias

`GET /api/v1/aliases/

Returns one regular alias that belongs to the authenticated account.

Path parameters

  • aliasId

Response fields

  • id
  • aliasAddress
  • forwardToEmail
  • description
  • isFavorite
  • ignoreEmails
  • allowedWebsiteOrDomain
  • allowSubdomains
  • outsideAllowedDomainAlertEnabled
  • outsideAllowedDomainAction

Response codes

  • 200 OK
  • 404 Not Found

Example

curl "http://Hide-My-Email.info/api/v1/aliases/alias_123" -H "secret: sk1_example"

Create alias

POST /api/v1/aliases

Request body fields

  • aliasLength - required integer
  • domain - required domain string
  • forwardToEmail - required destination address
  • description - required string, can be empty
  • ignoreEmails - required boolean
  • useCustomAliasName - required boolean
  • customAliasName - optional string; required when useCustomAliasName is true
  • allowedWebsiteOrDomain - optional URL or bare domain; stored and returned as normalized host/domain only
  • allowSubdomains - optional boolean; defaults to true when allowedWebsiteOrDomain is empty
  • outsideAllowedDomainAlertEnabled - optional boolean; ignored when allowedWebsiteOrDomain is empty
  • outsideAllowedDomainAction - optional string: RejectTemporary, RejectPermanent, or Quarantine

Response fields

  • success
  • message
  • alias
  • warningMessage

The nested alias object contains:

  • id
  • aliasAddress
  • forwardToEmail
  • description
  • isFavorite
  • ignoreEmails
  • allowedWebsiteOrDomain
  • allowSubdomains
  • outsideAllowedDomainAlertEnabled
  • outsideAllowedDomainAction

When outsideAllowedDomainAction is Quarantine, the sender-side delivery is accepted, but the message is not forwarded to the alias recipient unless the sender was explicitly allowed on the Anti-SPAM / AV page.

The service validates that the resolved account is allowed to use the selected domain and alias length, including plan-gated checks for account-defined alias lengths. When useCustomAliasName is true, the service also validates whether the account is allowed to request an exact alias name in the selected domain:

  • exact alias names in account-owned domains require a plan that includes Custom aliases
  • exact alias names in public domains require an unused custom public alias request add-on

Exact alias names are globally unique across accounts. A name is also treated as unavailable when the same alias was deleted earlier and is still inside the 5-year deleted-alias retention period.

The created alias starts forwarding immediately after creation. When the selected domain is a public domain, the account can create at most one alias per minute through this endpoint. The cooldown does not apply to aliases created in domains owned by the current account. When an exact alias name is created in a public domain, one unused custom public alias request is consumed immediately and the action cannot be reversed.

Response codes

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized

Example

curl -X POST "http://Hide-My-Email.info/api/v1/aliases" \
  -H "secret: sk1_example" \
  -H "x-account-access-id: accid_example" \
  -H "Content-Type: application/json" \
  -d "{\"aliasLength\":12,\"domain\":\"hide-my-email.info\",\"forwardToEmail\":\"user@example.com\",\"description\":\"Checkout alias\",\"ignoreEmails\":false}"

curl -X POST "http://Hide-My-Email.info/api/v1/aliases" \
  -H "secret: sk1_example" \
  -H "x-account-access-id: accid_example" \
  -H "Content-Type: application/json" \
  -d "{\"aliasLength\":12,\"domain\":\"hide-my-email.info\",\"forwardToEmail\":\"user@example.com\",\"description\":\"Branded alias\",\"ignoreEmails\":false,\"useCustomAliasName\":true,\"customAliasName\":\"Sales-Team\"}"

Check custom alias name availability

POST /api/v1/aliases/availability

Checks whether an exact alias name is currently available in the selected domain for the authenticated account.

The service first validates whether the account is allowed to request an exact alias name in the selected domain:

  • account-owned domains require the Custom aliases feature
  • public domains require at least one unused custom public alias request add-on

Only after that validation succeeds does the service check whether the name is globally available.

The account can call this endpoint at most once every 30 seconds. Repeating the request before the cooldown ends extends the cooldown from the moment of the repeated request.

Request body fields

  • domain - required domain string
  • customAliasName - required string

Response fields

  • success
  • isAvailable
  • message
  • retryAfterSeconds - optional integer; returned when the next availability check is still on cooldown

Response codes

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized

Example

curl -X POST "http://Hide-My-Email.info/api/v1/aliases/availability" \
  -H "secret: sk1_example" \
  -H "x-account-access-id: accid_example" \
  -H "Content-Type: application/json" \
  -d "{\"domain\":\"hide-my-email.info\",\"customAliasName\":\"Sales-Team\"}"

Update alias

`PUT /api/v1/aliases/

Updates only the mutable properties of an existing alias. The alias address itself, its domain, and its generated length are not changed by this endpoint.

Path parameters

  • aliasId

Request body fields

  • forwardToEmail
  • description
  • isFavorite
  • ignoreEmails
  • allowedWebsiteOrDomain
  • allowSubdomains
  • outsideAllowedDomainAlertEnabled
  • outsideAllowedDomainAction

Response fields

  • success
  • message
  • alias
  • warningMessage

The nested alias object contains:

  • id
  • aliasAddress
  • forwardToEmail
  • description
  • isFavorite
  • ignoreEmails

Example

curl -X PUT "http://Hide-My-Email.info/api/v1/aliases/alias_123" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"forwardToEmail\":\"billing@example.com\",\"description\":\"Updated\",\"isFavorite\":true,\"ignoreEmails\":false}"

Update alias favorite flag

`PATCH /api/v1/aliases/

Marks or unmarks an alias as favorite without changing its forwarding settings.

Request body fields

  • isFavorite

Response fields

  • success
  • message
  • alias

The nested alias object contains:

  • id
  • aliasAddress
  • forwardToEmail
  • description
  • isFavorite
  • ignoreEmails

Example

curl -X PATCH "http://Hide-My-Email.info/api/v1/aliases/alias_123/favorite" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"isFavorite\":true}"

Update alias ignore mode

`PATCH /api/v1/aliases/

Enables or disables ignore mode for an alias. When ignore mode is enabled, matching incoming mail is intentionally discarded instead of forwarded.

Request body fields

  • ignoreEmails

Response fields

  • success
  • message
  • alias

The nested alias object contains:

  • id
  • aliasAddress
  • forwardToEmail
  • description
  • isFavorite
  • ignoreEmails

Example

curl -X PATCH "http://Hide-My-Email.info/api/v1/aliases/alias_123/ignore" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"ignoreEmails\":true}"

Delete alias

`DELETE /api/v1/aliases/

Deletes an alias from the account UI. After deletion, the alias remains reserved for 30 days and incoming mail is still forwarded during that period; the alias is fully released only after the retention period ends. In addition, the service keeps a hash-only record of the deleted alias for 5 years so the exact same alias address cannot be generated again during that period.

Response fields

  • success
  • message

Example

curl -X DELETE "http://Hide-My-Email.info/api/v1/aliases/alias_123" -H "secret: sk1_example"

Alias Length Endpoints

List effective alias lengths

GET /api/v1/aliases/lengths

Returns the alias lengths currently available to the account after applying public defaults, public per-domain entries, and any user-owned lengths the account is allowed to use.

Response fields

  • []
  • [].length
  • [].name
  • [].domain
  • [].isUserOwned
  • [].isDefault
  • [].isFavorite

Example

curl "http://Hide-My-Email.info/api/v1/aliases/lengths" -H "secret: sk1_example"

List user-owned alias lengths

GET /api/v1/aliases/lengths/user

Returns only alias lengths created by the authenticated account.

Response fields

  • []
  • [].id
  • [].length
  • [].name
  • [].domain
  • [].isActive
  • [].isDefault
  • [].isFavorite

Example

curl "http://Hide-My-Email.info/api/v1/aliases/lengths/user" -H "secret: sk1_example"

Read one user-owned alias length

`GET /api/v1/aliases/lengths/user/

Returns one user-owned alias length definition.

Path parameters

  • aliasLengthId

Response fields

  • id
  • length
  • name
  • domain
  • isActive
  • isDefault
  • isFavorite

Example

curl "http://Hide-My-Email.info/api/v1/aliases/lengths/user/len_123" -H "secret: sk1_example"

Create user-owned alias length

POST /api/v1/aliases/lengths/user

Creates a custom alias length owned by the account. Account-owned alias lengths are only usable when the account is allowed to use custom domains / custom alias-length functionality in the current plan.

Request body fields

  • length
  • name
  • domain - optional, null means global
  • isActive

Response fields

  • success
  • message
  • aliasLength

Example

curl -X POST "http://Hide-My-Email.info/api/v1/aliases/lengths/user" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"length\":14,\"name\":\"Checkout\",\"domain\":null,\"isActive\":true}"

Update user-owned alias length

`PUT /api/v1/aliases/lengths/user/

Updates one custom alias length owned by the account.

Request body fields

  • length
  • name
  • domain
  • isActive

Response fields

  • success
  • message
  • aliasLength

Example

curl -X PUT "http://Hide-My-Email.info/api/v1/aliases/lengths/user/len_123" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"length\":14,\"name\":\"Checkout\",\"domain\":\"example.com\",\"isActive\":true}"

Delete user-owned alias length

`DELETE /api/v1/aliases/lengths/user/

Deletes one custom alias length owned by the account.

Response fields

  • success
  • message

Example

curl -X DELETE "http://Hide-My-Email.info/api/v1/aliases/lengths/user/len_123" -H "secret: sk1_example"

Update alias length favorite flag

`PATCH /api/v1/aliases/lengths/user/

Marks or unmarks a custom alias length as favorite.

Request body fields

  • isFavorite

Response fields

  • success
  • message
  • aliasLength

Example

curl -X PATCH "http://Hide-My-Email.info/api/v1/aliases/lengths/user/len_123/favorite" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"isFavorite\":true}"

Update default alias length

`PATCH /api/v1/aliases/lengths/user/

Sets the account default alias length that is used by the UI and API flows when no other explicit alias length is chosen.

Request body fields

  • isDefault

Response fields

  • success
  • message
  • aliasLength

Example

curl -X PATCH "http://Hide-My-Email.info/api/v1/aliases/lengths/user/len_123/default" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"isDefault\":true}"

Clear default alias length

DELETE /api/v1/aliases/lengths/user/default

Clears the account-owned default alias length and falls back to the effective catalog default available to the account.

Response fields

  • success
  • message

Example

curl -X DELETE "http://Hide-My-Email.info/api/v1/aliases/lengths/user/default" -H "secret: sk1_example"

Domain Endpoints

List effective domains

GET /api/v1/domains

Returns domains available to the authenticated account, including public domains and any user-owned domains that remain active for the account.

Response fields

  • []
  • [].id
  • [].domain
  • [].description
  • [].isActive
  • [].isVerified
  • [].isDefault
  • [].isFavorite
  • [].autoGenerateAlias
  • [].allowGlobalAliasLengths
  • [].messageLimit

Example

curl "http://Hide-My-Email.info/api/v1/domains" -H "secret: sk1_example"

Read domain catalog settings

GET /api/v1/domains/settings

Returns account preferences that affect how public domains are exposed to the account.

Response fields

  • includePublicDomains
  • defaultPublicDomain
  • publicDomains[]

Example

curl "http://Hide-My-Email.info/api/v1/domains/settings" -H "secret: sk1_example"

Update domain catalog settings

PUT /api/v1/domains/settings

Updates account preferences for using public domains in alias creation flows.

Request body fields

  • includePublicDomains
  • defaultPublicDomain

Response fields

  • includePublicDomains
  • defaultPublicDomain
  • publicDomains[]

Example

curl -X PUT "http://Hide-My-Email.info/api/v1/domains/settings" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"includePublicDomains\":true,\"defaultPublicDomain\":\"hide-my-email.info\"}"

Read one user-owned domain

`GET /api/v1/domains/user/

Returns one custom domain owned by the authenticated account.

Response fields

  • id
  • domain
  • description
  • isActive
  • isVerified
  • isDefault
  • isFavorite
  • autoGenerateAlias
  • allowGlobalAliasLengths
  • messageLimit

Example

curl "http://Hide-My-Email.info/api/v1/domains/user/domain_123" -H "secret: sk1_example"

Read detailed domain view

`GET /api/v1/domains/user/

Returns the detailed verification and DNS view for one custom domain owned by the authenticated account.

Response fields

  • id
  • domain
  • description
  • isActive
  • isVerified
  • requiresOwnershipVerification
  • ownershipDnsRecord
  • ownershipDnsRecord.type
  • ownershipDnsRecord.host
  • ownershipDnsRecord.priority
  • ownershipDnsRecord.value
  • ownershipDnsRecord.isVerified
  • isDefault
  • isFavorite
  • autoGenerateAlias
  • isRootDomain
  • messageLimit
  • maxAllowedMessageLimit
  • receivingDnsRecords[]
  • sendingDnsRecords[]

Example

curl "http://Hide-My-Email.info/api/v1/domains/user/domain_123/details" -H "secret: sk1_example"

Read domain ownership diagnostics

`GET /api/v1/domains/user/

Returns diagnostic data useful while troubleshooting ownership verification. This endpoint is intended for verification troubleshooting only and does not change domain state.

Response codes

  • 200 OK
  • 404 Not Found

Example

curl "http://Hide-My-Email.info/api/v1/domains/user/domain_123/ownership-debug" -H "secret: sk1_example"

Create user-owned domain

POST /api/v1/domains/user

Creates a custom domain owned by the authenticated account. The domain is not usable for normal forwarding flows until its ownership and required DNS records are verified.

Request body fields

  • domain
  • description
  • isActive

Response fields

  • success
  • message
  • domain

Example

curl -X POST "http://Hide-My-Email.info/api/v1/domains/user" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"domain\":\"example.com\",\"description\":\"My domain\",\"isActive\":true}"

Update user-owned domain

`PUT /api/v1/domains/user/

Updates the mutable properties of a user-owned domain. Verification requirements still apply after the update.

Request body fields

  • domain
  • description
  • isActive

Response fields

  • success
  • message
  • domain

Example

curl -X PUT "http://Hide-My-Email.info/api/v1/domains/user/domain_123" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"domain\":\"example.com\",\"description\":\"Updated\",\"isActive\":true}"

Update domain favorite flag

`PATCH /api/v1/domains/user/

Marks or unmarks a custom domain as favorite.

Request body fields

  • isFavorite

Response fields

  • success
  • message
  • domain

Response codes

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized
  • 404 Not Found

Example

curl -X PATCH "http://Hide-My-Email.info/api/v1/domains/user/domain_123/favorite" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"isFavorite\":true}"

Update default domain

`PATCH /api/v1/domains/user/

Sets the account default custom domain used by UI and API flows when a domain is not chosen explicitly.

Request body fields

  • isDefault

Response fields

  • success
  • message
  • domain

Response codes

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized
  • 404 Not Found

Example

curl -X PATCH "http://Hide-My-Email.info/api/v1/domains/user/domain_123/default" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"isDefault\":true}"

Update domain automatic alias generation

`PATCH /api/v1/domains/user/

Enables or disables automatic alias generation for this domain when incoming mail arrives for an unknown local part.

Request body fields

  • autoGenerateAlias

Response fields

  • success
  • message
  • domain

Response codes

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized
  • 404 Not Found

Example

curl -X PATCH "http://Hide-My-Email.info/api/v1/domains/user/domain_123/auto-generate-alias" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"autoGenerateAlias\":true}"

Update use of global alias lengths for a domain

`PATCH /api/v1/domains/user/

Controls whether the domain may use globally available alias lengths in addition to lengths defined specifically for that domain.

Request body fields

  • allowGlobalAliasLengths

Response fields

  • success
  • message
  • domain

Response codes

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized
  • 404 Not Found

Example

curl -X PATCH "http://Hide-My-Email.info/api/v1/domains/user/domain_123/allow-global-alias-lengths" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"allowGlobalAliasLengths\":true}"

Update per-domain message limit

`PATCH /api/v1/domains/user/

Overrides the effective message forwarding limit for this domain. Passing null clears the override and returns the domain to the account or plan default.

Request body fields

  • messageLimit - optional integer, null clears the override

Response fields

  • success
  • message
  • domain

Response codes

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized
  • 404 Not Found

Example

curl -X PATCH "http://Hide-My-Email.info/api/v1/domains/user/domain_123/message-limit" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"messageLimit\":1000}"

Clear default domain

DELETE /api/v1/domains/user/default

Clears the account default custom domain and falls back to the effective default chosen by account settings.

Response fields

  • success
  • message

Response codes

  • 200 OK
  • 401 Unauthorized

Example

curl -X DELETE "http://Hide-My-Email.info/api/v1/domains/user/default" -H "secret: sk1_example"

Trigger ownership verification

`PUT /api/v1/domains/user/

Requests a fresh verification attempt for the custom domain by checking the ownership and mail DNS records currently visible for that domain.

Response fields

  • success
  • message
  • domain

Response codes

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized
  • 404 Not Found

Example

curl -X PUT "http://Hide-My-Email.info/api/v1/domains/user/domain_123/verify" -H "secret: sk1_example"

Delete user-owned domain

`DELETE /api/v1/domains/user/

Deletes a custom domain owned by the account. After deletion, aliases that depended on that domain can no longer continue their normal delivery flow.

Response fields

  • success
  • message

Response codes

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized
  • 404 Not Found

Example

curl -X DELETE "http://Hide-My-Email.info/api/v1/domains/user/domain_123" -H "secret: sk1_example"

10-Minute Alias Endpoints

Read 10-minute alias state

GET /api/v1/aliases/10-minute/state

Returns the current monthly request usage and the destination e-mail options available for temporary aliases.

Response fields

  • usedRequestsThisMonth
  • allowedRequestsThisMonth
  • emailOptions[]
  • emailOptions[].id
  • emailOptions[].email
  • emailOptions[].isDefault
  • emailOptions[].isFavorite

Example

curl "http://Hide-My-Email.info/api/v1/aliases/10-minute/state" -H "secret: sk1_example"

Create a 10-minute alias

POST /api/v1/aliases/10-minute

Creates a temporary forwarding alias. Temporary aliases expire automatically and are intended for short-lived flows only. Temporary alias addresses are matched exactly as created; they do not use the long-term deleted-alias retention that applies to regular aliases.

Request body fields

  • forwardToEmail

Response fields

  • success
  • message
  • alias
  • alias.id
  • alias.aliasAddress
  • alias.forwardToEmail
  • alias.createdAtUtc
  • alias.expiresAtUtc
  • alias.maxExpiresAtUtc
  • usedRequestsThisMonth
  • allowedRequestsThisMonth

Example

curl -X POST "http://Hide-My-Email.info/api/v1/aliases/10-minute" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"forwardToEmail\":\"user@example.com\"}"

Extend a 10-minute alias

`POST /api/v1/aliases/10-minute/

Extends the lifetime of an existing temporary alias, within the service limits for that alias.

Path parameters

  • aliasId

Request body

  • None

Response fields

  • success
  • message
  • alias
  • usedRequestsThisMonth
  • allowedRequestsThisMonth

Example

curl -X POST "http://Hide-My-Email.info/api/v1/aliases/10-minute/tmp_123/extend" -H "secret: sk1_example"

Delete a 10-minute alias

`DELETE /api/v1/aliases/10-minute/

Deletes a temporary alias immediately. After expiry or deletion, mail sent to that alias is treated as sent to an unknown recipient and no longer consumes message forwarding limits.

Path parameters

  • aliasId

Response fields

  • success
  • message
  • usedRequestsThisMonth
  • allowedRequestsThisMonth

Example

curl -X DELETE "http://Hide-My-Email.info/api/v1/aliases/10-minute/tmp_123" -H "secret: sk1_example"
© 2026 PrivacyGuard.company. All rights reserved.