Hide-My-Email.info API Documentation
All documents

Account, E-mail Addresses, Secrets, and Linked Users

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

Authentication Headers

Common account-scoped headers

Required headers

  • secret: sk1_...
  • x-account-access-id: aid1....

Optional headers

  • Accept: application/json
  • Content-Type: application/json for requests with a JSON body

Common response codes

  • 200 OK request succeeded
  • 400 Bad Request validation failed
  • 401 Unauthorized missing or invalid secret or x-account-access-id
  • 403 Forbidden secret is valid but cannot be used for the requested API capability
  • 404 Not Found target object does not exist

Account Details

Read account details

GET /api/v1/account/details

Returns the basic account profile used by the web application and account-scoped API clients.

Response fields

  • accountId
  • supportId
  • currentEmail
  • taxIdVatId
  • autoGenerateAlias
  • allowGlobalAliasLengths

Example

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

Update tax ID / VAT ID

PUT /api/v1/account/details/tax-id

Updates the stored tax identifier used to prefill future billing flows. Changes affect future receipts and orders, not documents that were already issued.

Request body fields

  • taxIdVatId - optional string, pass null or empty value to clear it

Response fields

  • Same as GET /api/v1/account/details

Example

curl -X PUT "http://Hide-My-Email.info/api/v1/account/details/tax-id" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"taxIdVatId\":\"PL1234567890\"}"

Update automatic alias generation

PUT /api/v1/account/details/auto-generate-alias

Enables or disables account-level automatic alias generation for domains and flows that support it.

Request body fields

  • autoGenerateAlias - required boolean

Response fields

  • Same as GET /api/v1/account/details

Example

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

Update use of global alias lengths

PUT /api/v1/account/details/allow-global-alias-lengths

Controls whether the account may use globally available alias lengths in addition to per-domain or user-owned alias lengths.

Request body fields

  • allowGlobalAliasLengths - required boolean

Response fields

  • Same as GET /api/v1/account/details

Example

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

Change account e-mail address

POST /api/v1/account/details/email-change/send-current-code

Sends a verification code to the current account e-mail address as the first step of changing the account e-mail.

Auth: Session (browser-based authentication)

Request body

  • None

Response fields

  • success
  • message

Response codes

  • 200 OK
  • 400 Bad Request
  • 403 Forbidden (not authenticated via session)

Example

curl -X POST "http://Hide-My-Email.info/api/v1/account/details/email-change/send-current-code" \
  -H "Content-Type: application/json"

POST /api/v1/account/details/email-change/verify-current

Verifies the code sent to the current e-mail and sends a verification code to the new e-mail address.

Auth: Session (browser-based authentication)

Request body fields

  • currentEmailCode - required 6-digit code from current e-mail
  • newEmail - required new e-mail address

Response fields

  • success
  • message

Response codes

  • 200 OK
  • 400 Bad Request
  • 403 Forbidden (not authenticated via session)

Example

curl -X POST "http://Hide-My-Email.info/api/v1/account/details/email-change/verify-current" \
  -H "Content-Type: application/json" \
  -d "{\"currentEmailCode\":\"123456\",\"newEmail\":\"newemail@example.com\"}"

POST /api/v1/account/details/email-change/confirm-new

Confirms the new e-mail address by verifying the code sent to it.

Auth: Session (browser-based authentication)

Request body fields

  • newEmailCode - required 6-digit code from new e-mail

Response fields

  • success
  • message

Response codes

  • 200 OK
  • 400 Bad Request
  • 403 Forbidden (not authenticated via session)

Example

curl -X POST "http://Hide-My-Email.info/api/v1/account/details/email-change/confirm-new" \
  -H "Content-Type: application/json" \
  -d "{\"newEmailCode\":\"654321\"}"

Delete account

DELETE /api/v1/account/details/delete

Deletes the current account. Paid order records may remain retained for compliance retention. Deleting an account removes access to the service and removes account data from normal operation flows, but some billing and payment-related records may remain for legally required retention periods. The account e-mail address is blocked for 60 days by storing only its normalized hash, not the plaintext address, and the same normalized e-mail cannot be used to register a new account during that period.

Request body

  • None

Response fields

  • Typically an empty success response

Example

curl -X DELETE "http://Hide-My-Email.info/api/v1/account/details/delete" \
  -H "secret: sk1_example"

Account Settings

Read account settings

GET /api/v1/account/settings

Returns lightweight account settings used by the UI and API authentication flows.

Response fields

  • dashboardCompactMode
  • accountAccessId
  • qrAliasAdditionalContactFieldsExpanded
  • aliasEditAdditionalContactFieldsExpanded
  • welcomeWizardCompleted
  • serviceNotificationsEnabled
  • serviceNotificationsWarningThresholdPercent
  • serviceNotificationsCriticalThresholdPercent
  • antiSpamEnabled
  • antiSpamViolationAction
  • antiSpamLanguageSelectionMode
  • antiSpamSelectedLanguageCodes
  • antiSpamOutgoingForeignLanguageAlertEnabled

Example

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

Anti-SPAM settings and sender rules

GET /api/v1/account/anti-spam/supported-languages

Returns all language codes supported by the active language detector.

GET /api/v1/account/anti-spam/sender-rules

Returns the account sender-rule list used by the Anti-SPAM / AV page.

PUT /api/v1/account/anti-spam/enabled

Updates whether Anti-SPAM language filtering is enabled for the account.

PUT /api/v1/account/anti-spam/violation-action

Updates the action used when a detected language violates the configured policy.

PUT /api/v1/account/anti-spam/language-mode

Updates whether the selected language list is treated as Allowed or Excluded.

PUT /api/v1/account/anti-spam/language-codes

Updates the selected language-code list. The request body uses a single comma-separated languageCodes value.

PUT /api/v1/account/anti-spam/outgoing-alert-enabled

Updates whether outgoing foreign-language alerts are enabled.

PUT /api/v1/account/anti-spam/sender-rules/allowed

Toggles whether the specified sender is explicitly allowed.

POST /api/v1/account/anti-spam/alerts/poll

Returns new anti-spam alert notifications created after the supplied sinceUtc timestamp. The response may contain both outgoing foreign-language alerts and alias outside-domain alerts.

For alias outside-domain alerts:

  • alertType is AliasOutsideDomain
  • aliasId points to the affected alias when available
  • aliasAddress contains the affected alias address
  • allowedDomain contains the normalized allowed domain configured on the alias
  • triggeredAction is RejectTemporary, RejectPermanent, or Quarantine

Alias outside-domain alerts are created only when the alias had outsideAllowedDomainAlertEnabled = true. Explicitly allowed senders from the Anti-SPAM / AV page bypass alias outside-domain restrictions and do not generate these alerts.

Get usage limit alert status

GET /api/v1/account/settings/usage-limit-alert-status

Returns the current message usage alert status and thresholds for the account.

Response fields

  • isAlertEnabled
  • warningThresholdPercent
  • criticalThresholdPercent
  • currentUsagePercent
  • isWarningThresholdExceeded
  • isCriticalThresholdExceeded

Example

curl "http://Hide-My-Email.info/api/v1/account/settings/usage-limit-alert-status" \
  -H "secret: sk1_example"

Update dashboard view mode

PUT /api/v1/account/settings/dashboard-view-mode

Updates the dashboard display preference for the authenticated account.

Request body fields

  • compactMode - required boolean

Response codes

  • 204 No Content
  • 400 Bad Request

Example

curl -X PUT "http://Hide-My-Email.info/api/v1/account/settings/dashboard-view-mode" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"compactMode\":true}"

Update QR alias additional contact fields

PUT /api/v1/account/settings/qr-alias-additional-contact-fields

Updates whether additional contact fields are expanded in QR alias sharing.

Request body fields

  • expanded - required boolean

Response codes

  • 204 No Content
  • 400 Bad Request

Example

curl -X PUT "http://Hide-My-Email.info/api/v1/account/settings/qr-alias-additional-contact-fields" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"expanded\":true}"

Update alias edit additional contact fields

PUT /api/v1/account/settings/alias-edit-additional-contact-fields

Updates whether additional contact fields are expanded in alias editing.

Request body fields

  • expanded - required boolean

Response codes

  • 204 No Content
  • 400 Bad Request

Example

curl -X PUT "http://Hide-My-Email.info/api/v1/account/settings/alias-edit-additional-contact-fields" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"expanded\":true}"

Update welcome wizard status

PUT /api/v1/account/settings/welcome-wizard

Marks the welcome wizard as completed for the account.

Request body fields

  • completed - required boolean

Response codes

  • 204 No Content
  • 400 Bad Request

Example

curl -X PUT "http://Hide-My-Email.info/api/v1/account/settings/welcome-wizard" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"completed\":true}"

Update service notifications

PUT /api/v1/account/settings/service-notifications

Updates service notification settings and alert thresholds.

Request body fields

  • enabled - required boolean
  • warningThresholdPercent - required integer (0-100)
  • criticalThresholdPercent - required integer (0-100)

Response codes

  • 204 No Content
  • 400 Bad Request

Example

curl -X PUT "http://Hide-My-Email.info/api/v1/account/settings/service-notifications" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"enabled\":true,\"warningThresholdPercent\":75,\"criticalThresholdPercent\":90}"

Regenerate account access ID

POST /api/v1/account/settings/account-access-id/regenerate

Generates a new accountAccessId for the current account. API clients using secret authentication must use the new value after regeneration. A logged-in browser session can call this endpoint directly. When calling it through API credentials, the request must include both a valid secret and the current x-account-access-id.

Request body

  • None

Response fields

  • dashboardCompactMode
  • accountAccessId

Response codes

  • 200 OK
  • 401 Unauthorized
  • 403 Forbidden

Example

curl -X POST "http://Hide-My-Email.info/api/v1/account/settings/account-access-id/regenerate" \
  -H "secret: sk1_example" \
  -H "x-account-access-id: aid1_current_example"

Account E-Mail Addresses

List account e-mail addresses

GET /api/v1/account/emails

Returns additional e-mail addresses linked to the account that can be used as forwarding targets and account-level defaults.

Response fields

  • []
  • [].id
  • [].email
  • [].isDefault
  • [].isFavorite

Example

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

Add an account e-mail address

POST /api/v1/account/emails

Adds a verified e-mail address to the account. The address must first receive and return a valid verification code.

Request body fields

  • email - required
  • isDefault - required boolean
  • isFavorite - required boolean
  • verificationCode - required 6-digit verification code previously sent by POST /api/v1/account/emails/verification-code for the same target e-mail address

Response fields

  • success
  • message
  • email
  • email.id
  • email.email
  • email.isDefault
  • email.isFavorite

Response codes

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized

Example

curl -X POST "http://Hide-My-Email.info/api/v1/account/emails" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"user@example.com\",\"isDefault\":true,\"isFavorite\":false,\"verificationCode\":\"123456\"}"

Send verification code for account e-mail changes

POST /api/v1/account/emails/verification-code

Sends a verification code for adding a new account e-mail address or for changing the address value of an existing entry.

Rate limits

  • The same account can request a verification code for the same target address no more than once every 120 seconds.
  • The same account can request verification codes for different target addresses no more than once every 60 seconds.

Request body fields

  • email - required
  • emailId - optional when updating an existing address

Response fields

  • success
  • message
  • retryAfterSeconds

retryAfterSeconds is returned only for normal verification resend cooldowns. It is not a signal that the request was blocked by anti-abuse protection.

Example

curl -X POST "http://Hide-My-Email.info/api/v1/account/emails/verification-code" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"user@example.com\"}"

Update an existing account e-mail address

`PUT /api/v1/account/emails/

Updates one stored account e-mail address. Verification is required when the actual e-mail value changes.

Path parameters

  • emailId - target e-mail identifier

Request body fields

  • email
  • isDefault
  • isFavorite
  • verificationCode - required only when email changes; not required when updating only isDefault and/or isFavorite

Response fields

  • success
  • message
  • email

Example

curl -X PUT "http://Hide-My-Email.info/api/v1/account/emails/email_123" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"billing@example.com\",\"isDefault\":false,\"isFavorite\":true,\"verificationCode\":\"123456\"}"

Clear the default account e-mail address

DELETE /api/v1/account/emails/default

Clears the current default account e-mail address.

Response fields

  • success
  • message

Example

curl -X DELETE "http://Hide-My-Email.info/api/v1/account/emails/default" \
  -H "secret: sk1_example"

Delete an account e-mail address

`DELETE /api/v1/account/emails/

Removes one linked account e-mail address from the account.

Path parameters

  • emailId

Response fields

  • success
  • message

Example

curl -X DELETE "http://Hide-My-Email.info/api/v1/account/emails/email_123" \
  -H "secret: sk1_example"

Account Secrets

List account secrets

GET /api/v1/account/secrets

Returns the API secrets created for the account. The raw secret value is never returned by this endpoint.

Response fields

  • []
  • [].id
  • [].displayName
  • [].description
  • [].isFavorite
  • [].createdAtUtc

Example

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

Read one account secret metadata entry

`GET /api/v1/account/secrets/

Returns metadata for one account secret without revealing the raw secret itself.

Path parameters

  • secretId

Response fields

  • id
  • displayName
  • description
  • isFavorite
  • createdAtUtc

Example

curl "http://Hide-My-Email.info/api/v1/account/secrets/secret_123" \
  -H "secret: sk1_example"

Generate a new account secret

POST /api/v1/account/secrets/generate

Creates a new API secret for the account. The returned plainSecret is only shown once and must be stored by the client immediately.

Request body fields

  • description - required display description

Response fields

  • success
  • message
  • secret
  • secret.id
  • secret.displayName
  • secret.description
  • secret.isFavorite
  • secret.createdAtUtc
  • plainSecret - shown only at creation time

Example

curl -X POST "http://Hide-My-Email.info/api/v1/account/secrets/generate" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"description\":\"CI integration\"}"

Update secret favorite flag

`PUT /api/v1/account/secrets/

Marks or unmarks one account secret as favorite for UI management purposes.

Path parameters

  • secretId

Request body fields

  • isFavorite - required boolean

Response fields

  • success
  • message
  • secret

Example

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

Delete a secret

`DELETE /api/v1/account/secrets/

Revokes and deletes one account secret.

Path parameters

  • secretId

Response body: none.

Response codes

  • 204 No Content
  • 401 Unauthorized
  • 404 Not Found

Example

curl -X DELETE "http://Hide-My-Email.info/api/v1/account/secrets/secret_123" \
  -H "secret: sk1_example"

Linked Users

Read linked users page

GET /api/v1/account/users

Returns the linked-account state for the authenticated account, including invitations sent by the owner account and current membership in another owner's account, if any.

Response fields

  • ownerAccountId
  • ownerEmail
  • isLinkedToAnotherAccount
  • linkedOwnerAccountId
  • linkedOwnerEmail
  • usersAllowed
  • usersUsed
  • users[]
  • users[].invitationId
  • users[].inviteeEmail
  • users[].status
  • users[].memberAccountId
  • users[].memberCurrentEmail
  • users[].createdAtUtc
  • users[].expiresAtUtc
  • users[].respondedAtUtc
  • users[].linkedAtUtc
  • users[].messageLimit
  • users[].tenMinuteRequestLimit
  • users[].status values:
    • Invited - invitation is active and awaiting recipient action
    • Member - invitation was accepted and the invited account is linked
    • Rejected - recipient rejected the invitation
    • Removed - invitation or linked member was removed by the owner

Example

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

Read one linked user or invitation

`GET /api/v1/account/users/invitation/

Returns one linked-user or invitation entry from the current account users page.

Path parameters

  • invitationId

Response fields

  • invitationId
  • inviteeEmail
  • status
  • memberAccountId
  • memberCurrentEmail
  • createdAtUtc
  • expiresAtUtc
  • respondedAtUtc
  • linkedAtUtc
  • messageLimit
  • tenMinuteRequestLimit

Response codes

  • 200 OK
  • 401 Unauthorized
  • 404 Not Found

Example

curl "http://Hide-My-Email.info/api/v1/account/users/invitation/inv_123" \
  -H "secret: sk1_example"

Returns only the current relationship between the authenticated account and a possible owner account.

Response fields

  • isLinkedToAnotherAccount
  • linkedOwnerAccountId
  • linkedOwnerEmail

Example

curl "http://Hide-My-Email.info/api/v1/account/users/link-state" \
  -H "secret: sk1_example"

Invite a linked user

POST /api/v1/account/users/invite

Sends an invitation asking another account holder to join the current account's plan as a linked user. The invited person must still accept through the invitation link flow before the relationship becomes active.

Rate limits

  • The same account can send a new linked-account invitation no more than once every 60 seconds.

Request body fields

  • email - required
  • recaptchaToken - required

Response fields

  • success
  • message
  • user
  • page

user contains:

  • invitationId
  • inviteeEmail
  • status
  • memberAccountId
  • memberCurrentEmail
  • createdAtUtc
  • expiresAtUtc
  • respondedAtUtc
  • linkedAtUtc
  • messageLimit
  • tenMinuteRequestLimit

page contains:

  • ownerAccountId
  • ownerEmail
  • isLinkedToAnotherAccount
  • linkedOwnerAccountId
  • linkedOwnerEmail
  • usersAllowed
  • usersUsed
  • users[]

Example

curl -X POST "http://Hide-My-Email.info/api/v1/account/users/invite" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"member@example.com\",\"recaptchaToken\":\"token\"}"

Update linked user limits

`PATCH /api/v1/account/users/

Updates per-linked-user limits assigned by the owner account.

Path parameters

  • invitationId

Request body fields

  • messageLimit - optional integer
  • tenMinuteRequestLimit - optional integer

Response fields

  • success
  • message
  • user
  • page

Example

curl -X PATCH "http://Hide-My-Email.info/api/v1/account/users/inv_123/limits" \
  -H "secret: sk1_example" \
  -H "Content-Type: application/json" \
  -d "{\"messageLimit\":1000,\"tenMinuteRequestLimit\":50}"

Remove linked user or cancel invitation

`DELETE /api/v1/account/users/

Cancels a pending invitation or removes an already linked user from the owner account plan.

Path parameters

  • invitationId

Response fields

  • success
  • message
  • page

Example

curl -X DELETE "http://Hide-My-Email.info/api/v1/account/users/inv_123" \
  -H "secret: sk1_example"

Disconnect the current account from an owner plan

POST /api/v1/account/users/disconnect

Disconnects the current account from a linked owner plan. After disconnection, the current account loses access to service capacity provided by that owner plan.

Request body

  • None

Response fields

  • success
  • message
  • page

Example

curl -X POST "http://Hide-My-Email.info/api/v1/account/users/disconnect" \
  -H "secret: sk1_example"
© 2026 PrivacyGuard.company. All rights reserved.