Get started

tsmartSend documentation

tsmartSend is the email sending API of tsmart.ai. Your applications send password resets, order confirmations and notifications from your own verified domains with one HTTP request, and get delivery, bounce, open and click events back through webhooks.

What tsmartSend does

• Sends single emails and batches of up to 100, now or at a scheduled time up to 30 days ahead.
• Signs every email with DKIM for your domain and sends it from the tsmart.ai mail infrastructure.
• Records what happens to each email (sent, delivered, delayed, bounced, opened, clicked) and posts these events to your webhooks.
• Keeps a suppression list per company, so addresses that bounced permanently are not tried again.
• Lets you manage domains, API keys, webhooks and suppressions either in the company console or through the API with a full-access key.
• Sets up the company's mailboxes, alternate emails and groups through the same API, with the console's rules, so a script can move many domains and users at once.

tsmartSend is for transactional email that your application sends on behalf of your company. People who send from their mailbox in a mail app or a device use SMTP instead.

Base URL

Every request goes to:

https://send.tsmart.ai

Requests and responses are JSON over HTTPS. GET https://send.tsmart.ai/ answers without a key with a short description of the API, which is a quick way to check that your network can reach it.

Authentication

Every endpoint except the one above needs an API key, sent as a bearer token. Keys start with ts_ and are created in the company console under Apps → Core services → tsmartSend → API keys.

curl 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": "Your order has shipped",
    "html": "<p>Your order is on its way.</p>"
  }'

A key is shown only once. Keep it on the server, in a secret store or an environment variable, never in browser or mobile app code. API keys explains the two permissions, domain restrictions and revoking.

Libraries and the CLI

The official libraries have no dependencies and are downloaded from tsmart.ai. All of them read the key from the TSMART_API_KEY environment variable when you do not pass one.

Node.js

Node.js 18 or newer, ES modules, with TypeScript types.

npm install https://tsmart.ai/sdk/node/tsmart-sdk-1.1.1.tgz

import { Tsmart } from "@tsmart/sdk";

const tsmart = new Tsmart(process.env.TSMART_API_KEY);

const { data, error } = await tsmart.emails.send({
  from: "Acme <hello@acme.com>",
  to: "jane@example.com",
  subject: "Your order has shipped",
  html: "<p>Your order is on its way.</p>",
});
if (error) throw new Error(`${error.name}: ${error.message}`);
console.log(data.id);

Python

Python 3.8 or newer, standard library only.

pip install https://tsmart.ai/sdk/python/tsmart-1.1.1-py3-none-any.whl

from tsmart import Tsmart

client = Tsmart()  # reads TSMART_API_KEY

email = client.emails.send({
    "from": "Acme <hello@acme.com>",
    "to": "jane@example.com",
    "subject": "Your order has shipped",
    "html": "<p>Your order is on its way.</p>",
})
print(email["id"])

Command line

The tsmart command needs Node.js 18 or newer. Install it globally, or download the single file tsmart.mjs and run it with node tsmart.mjs.

npm install -g https://tsmart.ai/cli/tsmart-cli-1.1.0.tgz

tsmart login          # asks for the key and stores it for your user
tsmart emails send --from "Acme <hello@acme.com>" --to jane@example.com \
  --subject "Your order has shipped" --html "<p>Your order is on its way.</p>"

See Node.js SDK, Python SDK and CLI for the full reference.

Conventions

• Errors always have the same shape: { "statusCode": 422, "name": "validation_error", "message": "…" }. The names are listed in Limits and errors.
• Lists are paged with limit (1 to 100, default 20) and an after or before cursor, and return { "object": "list", "has_more": …, "data": [ … ] }.
• Emails, domains, keys, webhooks and suppressions are identified by UUIDs; webhook events by ids that start with msg_.
• Authenticated responses carry ratelimit-limit, ratelimit-remaining and ratelimit-reset headers (a restricted_api_key error does not). Each company may make 10 requests per second.

Where to go next