START HERE · Published 2026-10-06 · Updated 2026-10-06 · SecureSMTP

API conventions

Base URL, the key header, request format, how to read a response, and the limits every endpoint shares.

Base URL

Base URL
https://securessmtp.com/api/v1

Every request uses HTTPS. Bodies are JSON (Content-Type: application/json) and so are responses.

Authentication

Send the site’s API key in a header on every request. The header name is not case-sensitive.

Header
x-securessmtp-api-key: qcs_live_...

x-qcs-api-key is accepted too and works on every endpoint. The key decides which site the request belongs to — there is no separate site ID or site URL header. A key for a disabled site gets 403 site_disabled on the sending and forms endpoints.

The REST API does not accept Authorization: Bearer. Bearer tokens are only for the MCP server.

Reading a response

Check the body, not only the HTTP status. The sending endpoint answers HTTP 200 for some failures so that the WordPress plugin can fall back to WordPress’s own mailer. Successful responses, and every response from the mail, sequence and blocks endpoints, have an ok field:

Responses
// success
{ "ok": true, "sent": true, "mode": "domain", "message_id": "<[email protected]>" }

// failure — HTTP 200, but not sent
{ "ok": false, "sent": false, "reason": "over_quota" }

// failure — HTTP 400
{ "ok": false, "sent": false, "reason": "invalid_payload", "details": { "fieldErrors": { "to": ["Invalid email"] } } }

The sending and sequence endpoints name the problem in reason. The forms, sites and blocks endpoints name it in error. Every value is listed in the error catalogue.

HTTP status codes

StatusMeaning
200Request handled. Read ok (and blocked / email_sent on form submissions) to know whether it worked.
400The request is wrong: bad JSON, a field failed validation, or the content was flagged.
401No key, or the key is not valid.
403The site is disabled, sending on the site is paused, the email address on the account is not confirmed yet (email_not_verified), or the action is not allowed for this key.
404The form, sequence or block does not exist for this site.
410The hosted form was archived.
500Something failed on our side. Retry later; if it repeats, contact support.
503A site’s first email could not be checked just now. Retry after the number of seconds in the Retry-After header (120).

Limits

WhatLimitWhat you get
Sends per site120 in any 60 seconds (rejected and failed sends count too)200 with reason: "rate_limited"
Emails per monthYour plan’s monthly count200 with reason: "over_quota"
RecipientsUp to 50 each in to, cc and bcc400 invalid_payload
html / text500,000 characters each400 invalid_payload
AttachmentsUp to 20 files, 15 MB in total400 attachments_too_large
Request size25 MB413 from the web server
Form submissions per visitor IPMore than 3 in 60 seconds blocks that IP for 1 hour200 with blocked: true

See Plans and limits for the monthly counts.

Retries

  • There is no idempotency key. If a request times out and you send it again, the email can go out twice. Retry only on network errors, 500 and 503, wait a few seconds first (for 503, the number of seconds in the Retry-After header), and stop after two or three tries.
  • Do not retry 400 responses — the same request will fail the same way. Fix the request first.
  • For rate_limited, wait a minute. For over_quota, wait for the new month or upgrade.
  • Do not retry 403 sending_paused. The site stays paused until a person at SecureSMTP releases it. Open a support ticket at /support.
  • Do not retry 403 email_not_verified until the email address on your account is confirmed: open the confirm link we emailed you, then send again.

Versioning

All endpoints are under /api/v1. We add fields to responses without notice, so ignore fields you do not know. Unknown fields in a request body are ignored, not rejected.