/

API REFERENCE · Published 2026-10-06 · Updated 2026-10-06 · SecureSMTP

Change captcha settings

POST /api/v1/sites/captcha

POSThttps://securessmtp.com/api/v1/sites/captcha

Changes the site’s captcha provider and saves your own keys for it. Form submissions are then checked with this provider.

Headers

x-securessmtp-api-keystringrequired
The site’s API key (qcs_live_…). x-securesmtp-api-key and x-qcs-api-key are accepted too. See Sites and API keys.
Content-Typestringrequired
application/json

Body

provider'shared' | 'turnstile' | 'hcaptcha' | 'recaptcha' | 'recaptcha_v3' | 'none'required
shared uses our Turnstile key and needs no keys from you. none turns the captcha off. Both delete any keys saved before. The others use your own keys.
site_keystringoptional
Up to 200 characters. Your public site key. Required unless provider is shared or none.
secret_keystringoptional
Up to 500 characters. Your secret key. Stored encrypted (AES-256-GCM) and never returned. Required the first time; after that you may leave it out and the saved secret is kept. Send it again whenever you change provider.

Request

curl -X POST https://securessmtp.com/api/v1/sites/captcha \
  -H "x-securessmtp-api-key: $SECURESSMTP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "hcaptcha",
  "site_key": "10000000-ffff-ffff-ffff-000000000001",
  "secret_key": "0x0000000000000000000000000000000000000000"
}'

Response

The saved settings, in the same shape as GET /sites/captcha.

200
{
  "ok": true,
  "provider": "hcaptcha",
  "site_key": "10000000-ffff-ffff-ffff-000000000001",
  "widget_js": "https://js.hcaptcha.com/1/api.js",
  "widget_class": "h-captcha",
  "response_field": "h-captcha-response"
}
Response fields
okbooleanrequired
true.
provider'shared' | 'turnstile' | 'hcaptcha' | 'recaptcha' | 'recaptcha_v3' | 'none'required
The site’s captcha. shared is our own Cloudflare Turnstile key (the default). none means no captcha.
site_keystring | nullrequired
The public key to render the widget with. null for none.
widget_jsstring | nullrequired
The script to load on the page.
widget_classstring | nullrequired
The class of the element the widget mounts on (with data-sitekey set to site_key).
response_fieldstring | nullrequired
The form field the widget’s token is in. Send its value as captcha_token to POST /forms/submit.

Errors

Errors have an error field and no ok field.

HTTPValueMeaningWhat to do
401missing_api_keyNo key header was sent.Send the key in the x-securessmtp-api-key header.
401invalid_api_keyNo site has this key. Keys stop working as soon as they are rotated.Copy the current key from the dashboard, or rotate it to get a new one.
403site_disabledThe site is disabled.Check GET /blocks/status. See Blocks.
400invalid_jsonThe body is not valid JSON.Send a JSON body with Content-Type: application/json.
400invalid_payloadprovider is missing or not one of the values above, or a key is too long. details says which.Fix the fields listed in details.
400site_key_requiredA provider other than shared or none was sent without site_key.Send site_key.
400secret_key_required_on_first_saveNo secret is saved for the site yet and none was sent.Send secret_key.
500encryption_failedThe secret could not be stored. A message field has details.Retry. If it keeps failing, contact support.

See Spam protection.

Previous
Get captcha settings
Next
Check blocks