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
https://securessmtp.com/api/v1Every 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.
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.
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:
// success
{ "ok": true, "sent": true, "mode": "relay", "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
| Status | Meaning |
|---|---|
200 | Request handled. Read ok (and blocked / email_sent on form submissions) to know whether it worked. |
400 | The request is wrong: bad JSON, a field failed validation, or the content was flagged. |
401 | No key, or the key is not valid. |
403 | The site is disabled, or the action is not allowed for this key. |
404 | The form, sequence or block does not exist for this site. |
410 | The hosted form was archived. |
500 | Something failed on our side. Retry later; if it repeats, contact support. |
Limits
| What | Limit | What you get |
|---|---|---|
| Sends per site | 120 in any 60 seconds (rejected and failed sends count too) | 200 with reason: "rate_limited" |
| Emails per month | Your plan’s monthly count (relay mode only) | 200 with reason: "over_quota" |
| Recipients | Up to 50 each in to, cc and bcc | 400 invalid_payload |
| html / text | 500,000 characters each | 400 invalid_payload |
| Attachments | Up to 20 files, 15 MB in total | 400 attachments_too_large |
| Request size | 25 MB | 413 from the web server |
| Form submissions per visitor IP | More than 3 in 60 seconds blocks that IP for 1 hour | 200 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 and
500, wait a few seconds first, and stop after two or three tries. - Do not retry
400responses — the same request will fail the same way. Fix the request first. - For
rate_limited, wait a minute. Forover_quota, wait for the new month or upgrade.
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.