Get started

Quickstart

Four steps: create an API key, add and verify the domain you send from, send an email, and check what happened to it. You need a tsmart.ai company account and access to the DNS of your domain.

1. Create an API key

Sign in to the company console and open Apps → Core services → tsmartSend → API keys.
Under Create an API key, enter a name such as Production web shop.
Choose Full access for this quickstart, so the same key can also read the email back in step 4. For production, a Sending access key limited to one domain is the safer choice.
Click Create key and copy the key. It is shown only once.

Keep the key in an environment variable; the libraries and the CLI read TSMART_API_KEY.

Shell

export TSMART_API_KEY="ts_xxxxxxxx_…"

Managing tsmartSend in the console needs the API controls privilege. If the API keys page says you don't have access to tsmartSend, ask a company owner for the API controls privilege. More in API keys.

2. Add and verify your domain

You can only send from a domain your company has verified, and only once its SPF and DKIM records are published. If the domain is already used for mailboxes on tsmart.ai, it is verified already: check that the tsmartSend Domains tab shows it as ready and continue with step 3.

In the console open Account → Domains → Manage domains and add the domain, for example acme.com. You can use a subdomain such as notify.acme.com to keep application mail apart.
Publish the ownership record shown on the domain page at your DNS provider, then click Verify:
DNS
```
_tsmart-verify.acme.com   TXT   "tsmart-verify=<token from the console>"
```
After ownership is proven, the domain page lists the SPF and DKIM records (and recommends DMARC). Publish them and click Check DNS records. The domain is ready when SPF and DKIM are both OK.

The same steps work with the full-access key from step 1:

cURL

# Add the domain; the response lists the ownership TXT record to publish
curl -X POST https://send.tsmart.ai/domains \
  -H "Authorization: Bearer $TSMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "acme.com"}'

# After publishing the record: prove ownership, then (after publishing SPF and DKIM) check again
curl -X POST https://send.tsmart.ai/domains/<domain id>/verify \
  -H "Authorization: Bearer $TSMART_API_KEY"

# "status": "verified" means the domain can send
curl https://send.tsmart.ai/domains/<domain id> \
  -H "Authorization: Bearer $TSMART_API_KEY"

Domains and DNS lists every record with its exact value and explains how to merge SPF with an existing record.

3. Send your first email

Use an address on your verified domain as from. The response contains the id of the email.

cURL

curl -X POST https://send.tsmart.ai/emails \
  -H "Authorization: Bearer $TSMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": ["jane@example.com"],
    "subject": "Hello from tsmartSend",
    "html": "<p>It works.</p>"
  }'

Response

{ "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" }

Node.js

// npm install https://tsmart.ai/sdk/node/tsmart-sdk-1.1.1.tgz
import { Tsmart } from "@tsmart/sdk";

const tsmart = new Tsmart(); // reads TSMART_API_KEY

const { data, error } = await tsmart.emails.send({
  from: "Acme <hello@acme.com>",
  to: ["jane@example.com"],
  subject: "Hello from tsmartSend",
  html: "<p>It works.</p>",
});
if (error) {
  console.error(error.statusCode, error.name, error.message);
} else {
  console.log("Email id:", data.id);
}

Python

# pip install https://tsmart.ai/sdk/python/tsmart-1.1.1-py3-none-any.whl
from tsmart import Tsmart, TsmartError

client = Tsmart()  # reads TSMART_API_KEY

try:
    email = client.emails.send({
        "from": "Acme <hello@acme.com>",
        "to": ["jane@example.com"],
        "subject": "Hello from tsmartSend",
        "html": "<p>It works.</p>",
    })
    print("Email id:", email["id"])
except TsmartError as e:
    print(e.status_code, e.name, e.message)

CLI

# npm install -g https://tsmart.ai/cli/tsmart-cli-1.1.0.tgz
tsmart emails send \
  --from "Acme <hello@acme.com>" \
  --to jane@example.com \
  --subject "Hello from tsmartSend" \
  --html "<p>It works.</p>"

4. Check the email's status

last_event shows the latest thing that happened to the email: sent once our mail server accepted it, then delivered when the recipient's server accepted it (or delivery_delayed, bounced). Delivery results usually arrive within a minute.

cURL

curl https://send.tsmart.ai/emails/4ef9a417-02e9-4d39-ad75-9611e0fcc33c \
  -H "Authorization: Bearer $TSMART_API_KEY"

Response

{
  "object": "email",
  "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
  "message_id": "<4ef9a417-02e9-4d39-ad75-9611e0fcc33c@acme.com>",
  "to": ["jane@example.com"],
  "from": "Acme <hello@acme.com>",
  "created_at": "2026-10-12 09:41:05.120345+00",
  "subject": "Hello from tsmartSend",
  "bcc": [],
  "cc": [],
  "reply_to": [],
  "last_event": "delivered",
  "scheduled_at": null,
  "html": "<p>It works.</p>",
  "text": null,
  "tags": []
}

Node.js

const { data } = await tsmart.emails.get("4ef9a417-02e9-4d39-ad75-9611e0fcc33c");
console.log(data.last_event);

// Every event in time order (sent, delivered, opened …)
const { data: events } = await tsmart.emails.events("4ef9a417-02e9-4d39-ad75-9611e0fcc33c");
for (const e of events.data) console.log(e.created_at, e.type, e.recipient);

Python

email = client.emails.get("4ef9a417-02e9-4d39-ad75-9611e0fcc33c")
print(email["last_event"])

CLI

tsmart emails get 4ef9a417-02e9-4d39-ad75-9611e0fcc33c

You can also follow the email in the console under tsmartSend → Emails. Reading emails needs a full-access key; a sending-access key gets 401 restricted_api_key.

Next steps

Receive eventsGet delivered, bounced, opened and clicked events pushed to your server. Sending emailAttachments, tags, scheduling, batches and safe retries. Production keysSending-only keys, domain restriction and IP allow-list.