Send published templates from your own systems

01

Authentication

Every call is authenticated by a workspace API key, sent as a bearer token. Cookies and sessions are never accepted on these routes. GET /api/v1/public/whoami answers with the key’s workspace, owner and scopes, which makes it a useful first check that a key works.

• A key starts with stk_. Its secret is shown once, when an administrator creates the key under Administration › API keys. Only a hash of the secret is kept, so store the secret the way you store a password.
• The Authorization scheme is case-insensitive. A key in the query string is never accepted, because it would reach logs.
• A key acts as the person who created it, the owner. It can do only what the owner may do, and only within its scopes.
• An administrator’s own administrative powers never pass to a key, so a key created by an administrator still cannot change settings.
• A key works only inside the workspace it was created in. Ids from another workspace answer 404.

1curl https://app.securethread.co/api/v1/public/whoami \2  -H "Authorization: Bearer stk_<your-key>"

02

Scopes and access limits

Each key carries one or more scopes. A route refuses a key that lacks its scope with 403.

• A key can be limited to address ranges, written in CIDR form such as 203.0.113.0/24. A call from any other address is refused with 403, whatever the scopes.
• A key can expire after 30, 90 or 365 days, or never. A revoked or expired key answers 401 at once.
• Revoking a key takes effect on its next call. If the owner’s account is deactivated, every key the owner created stops working.

03

Templates, mailboxes and contacts

These routes list the templates and mailboxes the owner may use before a send, and let an integration manage the owner’s own contacts. The examples use [email protected] and Alex Example as sample people, and the ids are placeholders.

• GET /api/v1/public/templates needs the templates scope. It lists the published templates the owner may use, with the variables of each published version. Only metadata leaves the server: never the subject, preview text or body.
• Templates take q (search text, up to 120 characters), page (default 1) and pageSize (default 25, up to 100). Each item has an id, name, description, variables and updatedAt.
• GET /api/v1/public/mailboxes needs the send scope. It lists the mailboxes the owner may send from right now: their own and the shared ones granted to them. A mailbox that is signed out or suspended is left out. The id is the connectionId a send names. No server, sign-in or health detail is returned.
• GET /api/v1/public/contacts needs the contacts scope. Its q parameter matches the address, first name, last name or company, and it takes page and pageSize.
• POST /api/v1/public/contacts needs the contacts scope. It creates the owner’s contact for an address, or updates the contact the owner already has. It answers 201 with the contact when it is created and 200 when an existing contact is updated.
• A contact has an id, email, first name, last name, company, job title, notes, createdAt and updatedAt. Addresses are matched without regard to case, and only the fields you send change.
• Contacts made through the API are personal. The key cannot make a shared contact, and a visibility field is refused with 400. Each contact change is audited under the owner, as it is in the web app.

1# Published templates the owner may use2curl "https://app.securethread.co/api/v1/public/templates?q=interview&pageSize=10" \3  -H "Authorization: Bearer stk_<your-key>"4 5# Mailboxes the owner may send from6curl https://app.securethread.co/api/v1/public/mailboxes \7  -H "Authorization: Bearer stk_<your-key>"8 9# Contacts the owner manages10curl "https://app.securethread.co/api/v1/public/contacts?q=Example&pageSize=25" \11  -H "Authorization: Bearer stk_<your-key>"12 13# Create a contact, or update the one the owner already has14curl -X POST https://app.securethread.co/api/v1/public/contacts \15  -H "Authorization: Bearer stk_<your-key>" \16  -H "Content-Type: application/json" \17  -d '{ "email": "[email protected]", "firstName": "Alex", "company": "Example Ltd" }'

04

Send a message

POST /api/v1/public/messages needs the send scope. It sends one message from a template’s published version, through the same send path the web composer uses. The subject, preview text and body come from the template, and the request cannot set them. Send a unique Idempotency-Key with each message, as described under Idempotency and rate limits.

• 201 Created means the message is with the sending queue. The answer has status QUEUED, the messageId, and a Location header that points to GET /api/v1/public/messages/{messageId}.
• 202 Accepted means the owner’s account requires an administrator’s approval first. The answer has status PENDING_APPROVAL, a null messageId and an approvalRequestId. Nothing is queued until a different administrator approves the request.
• Neither answer says that the recipient has the message. Check the status with GET /api/v1/public/messages/{id}.
• Every send gate applies as it does in the web app: the mailbox’s access, the organization’s sending domains, the sandbox, approvals, the content policy, the plan’s limits and the send rate limits. A send refused by one of them returns the same error the web app would show, with its status code.
• The approval rules for AI assistant sends apply to assistants, not to API keys. An account that needs approval for every send is held whichever way it sends.

1curl -X POST https://app.securethread.co/api/v1/public/messages \2  -H "Authorization: Bearer stk_<your-key>" \3  -H "Content-Type: application/json" \4  -H "Idempotency-Key: <unique-key-per-message>" \5  -d '{6    "templateId": "<template-id>",7    "connectionId": "<mailbox-id>",8    "to": [{ "email": "[email protected]", "name": "Casey Example" }],9    "variables": { "first_name": "Casey", "interview_date": "Monday 3 November" }10  }'

05

Message status

GET /api/v1/public/messages/{id} needs the read scope. It returns the status of a message the owner sent. Another person’s message, or one in another workspace, answers 404.

• acceptedAt is when the provider accepted the message. Accepted is not proof that the recipient has it. Nothing on this endpoint reports what happens after that.
• failureReason is set while a send is failing or being tried again. It is written in plain English, never in the provider’s own words.
• When the outcome is not known, failureReason says that the provider may have accepted the message. Check with the recipient before sending it again.
• To learn about changes as they happen, subscribe to event webhooks instead of polling. Each webhook call carries webhook-id, webhook-timestamp and webhook-signature. Check the signature against the endpoint’s secret before trusting a payload.

1{2  "id": "<message-id>",3  "status": "FAILED",4  "createdAt": "2026-10-25T09:31:02.000Z",5  "acceptedAt": null,6  "recipientCount": 1,7  "failureReason": "SecureThread could not sign in to the mailbox. Reconnect the mailbox, then send the message again."8}

06

Idempotency and rate limits

Send a unique Idempotency-Key with each message, so that a retry cannot send the message twice. Rate limits are counted per API key over a rolling five-minute window, and a call over a budget answers 429 RATE_LIMITED with a Retry-After header.

• Use 8 to 128 visible ASCII characters for the key, such as a UUID.
• A retry with the same key and the same request returns the first answer, with the header Idempotent-Replayed: true. The message is not sent twice.
• The same key with a different request is refused with 422 IDEMPOTENCY_KEY_REUSED. Use a new key for new content.
• A retry that arrives while the first call is still being handled answers 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Wait that many seconds, then retry with the same key.
• The key is remembered for 24 hours and belongs to the key that sent it.
• Without the header, the message is still sent once, but a retry sends it again. Send the header from any automation that retries.
• A presented key that does not exist is also limited per client address, so guessing keys cannot run without limit.
• A send also counts against the owner’s own send budget of 120 calls per five minutes, which the web app’s sends share. The owner’s keys together cannot send more than the owner could from the web app in the same window.

07

Errors

Every error uses the same envelope. Each message is written for a person, and the details array, when present, names the field that needs attention.

1{2  "error": {3    "code": "FORBIDDEN",4    "message": "This API key does not have the scope this action needs.",5    "details": []6  },7  "requestId": "req_example",8  "timestamp": "2026-10-25T09:30:00.000Z"9}

08

Versions and stability

The routes on this page are the stable surface of the public API. They all live under /api/v1/public/, and a version path marks any change that would break them.

• A change that would break a stable route, such as removing a field, a route or a status code, needs a new version path.
• Adding an optional field is not a breaking change, so ignore fields you do not know.