Get started

API keys

Every request to tsmartSend carries an API key. A key belongs to the company, has one of two permissions, can be limited to one sending domain, and is shown only once.

Key format

A key is ts_, an 8-character id, an underscore and a 32-character secret, letters and digits only:

ts_8Kq2Lm7P_…

The first part (ts_8Kq2Lm7P) is shown in the key list so you can tell keys apart. Only a SHA-256 hash of the whole key is stored, so nobody can display the key again after it was created. Send it as a bearer token:

Authorization: Bearer ts_8Kq2Lm7P_…

Permissions

Full-access keys act with their creator's rights

A full-access key can never do more through the API than the person who created it may do in the console. The creator's privileges are checked on every management call, so a key loses rights as soon as its creator does (a changed role, or removal from the company). Sending needs no privilege, but every key, sending-access keys included, works only while its creator still has access to the company.

When the creator lacks the right, the API answers 403 invalid_permission. A key created through the API acts for the same person as the key that created it.

When an admin is removed from the company, every key they created is revoked at once and the emails scheduled with those keys are canceled; the audit log lists each revoked key. A key whose creator has lost access in another way, for example because the account was disabled, is refused with 403 invalid_api_key and its scheduled emails are canceled when they come due. Give long-lived integrations keys created by a person who stays with the company, and replace the keys of anyone who leaves.

Domain restriction

A sending-access key can be limited to one of the company's verified domains. It then sends only from that domain; any other from address is refused with 403 invalid_from_address. A full-access key always covers every domain of the company.

Create a key

In the console

1. Open Apps → Core services → tsmartSend → API keys.
2. Under Create an API key, enter a name of up to 50 characters.
3. Choose Full access or Sending access.
4. For a sending-access key, optionally choose the one domain it may send from.
5. Click Create key and copy the key now. It is not shown again.

The page needs the API controls privilege.

With the API

A full-access key can create further keys. The new key is returned once, in token.

curl -X POST https://send.tsmart.ai/api-keys \
  -H "Authorization: Bearer $TSMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Web shop", "permission": "sending_access", "domain_id": "b7c1e0a2-5d0f-4a51-9a64-0f3c2a7d9e11"}'

{
  "id": "0b8e6d6c-6a3e-4c5e-8f43-2f1d8a9b7c10",
  "object": "api_key",
  "token": "ts_8Kq2Lm7P_…"
}

const { data, error } = await tsmart.apiKeys.create({
  name: "Web shop",
  permission: "sending_access",
  domain_id: "b7c1e0a2-5d0f-4a51-9a64-0f3c2a7d9e11",
});
console.log(data.token); // store it now

key = client.api_keys.create({
    "name": "Web shop",
    "permission": "sending_access",
    "domain_id": "b7c1e0a2-5d0f-4a51-9a64-0f3c2a7d9e11",
})
print(key["token"])  # store it now

GET /api-keys lists active keys with their name, permission, domain_id, created_at and last_used_at, never the key itself. PATCH /api-keys/{id} renames a key. See the API reference.

Storing keys

• Keep keys on the server: in a secret store or an environment variable (TSMART_API_KEY).
• Never put a key in browser JavaScript, a mobile app, a public repository or a support ticket.
• Use a separate key per application and environment, so you can revoke one without touching the others.
• Give applications that only send a sending-access key restricted to their domain.

The tsmart.ai security center's secret scanning recognizes the ts_ key format, so a key that leaks into a scanned repository is reported.

Revoke a key

Revoke a key in the console (API keys → Revoke) or with DELETE /api-keys/{id}. Revoking takes effect at once: the next request with the key gets 403 invalid_api_key.

To rotate a key without downtime: create the new key, deploy it, check its last_used_at, then revoke the old one.

curl -X DELETE https://send.tsmart.ai/api-keys/0b8e6d6c-6a3e-4c5e-8f43-2f1d8a9b7c10 \
  -H "Authorization: Bearer $TSMART_API_KEY"

Company-wide controls

IP allow-list

Under Security → Access and data control → API controls a company can list the addresses or ranges (CIDR) that may call the API. While the list is not empty, calls with any of the company's keys from other addresses are refused with 403 ip_not_allowed. Remember to include the outgoing addresses of every server and CI runner that sends.

Service switch

tsmartSend can be turned off for the company under Apps → Core services → Service status. While it is off, every call gets 403 service_disabled, and scheduled emails that come due fail with an email.failed event.

Authentication errors

All other errors are listed in Limits and errors.