Documentation menu

Libraries and tools

MCP server

tsmartSend is also a remote MCP server at https://send.tsmart.ai/mcp. An agent that speaks the Model Context Protocol can send email, follow its delivery, cancel a scheduled email and make a domain ready to send, with your company's API key. There is nothing to install.

Connect an agent

Add a remote server with this address and your API key in the Authorization header. Most clients read a configuration like this one:

MCP configuration
{
  "mcpServers": {
    "tsmart-send": {
      "type": "http",
      "url": "https://send.tsmart.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY, or better keep the key out of the file: most clients read it from an environment variable in their own syntax, for example ${TSMART_API_KEY} or ${env:TSMART_API_KEY}. The console shows the same configuration under tsmartSend → Overview → Connect an AI agent (MCP).

Which key to use

The key's own permissions apply to every tool, exactly as over the REST API (see API keys):

  • A sending-access key can use send_email only, and only from its domain if it is restricted to one. The other tools answer restricted_api_key.
  • A full-access key can use every tool, within the privileges of the person who created it. setup_sending_domain needs a key created by the company owner.

Tools

Each tool runs one endpoint of the API with your key, with the same validation and the same answers.

ToolWhat it doesEndpointKey
send_emailSends one email now, or later with scheduled_at. Returns its id.POST /emailsany
get_emailStatus and details of one email. The bodies (kept three days) only with include_body: true.GET /emails/{id}full access
list_email_eventsWhat happened to one email, oldest first: sent, delivered, bounced, opened …GET /emails/{id}/eventsfull access
list_emailsEmails sent by the company, newest first.GET /emailsfull access
cancel_scheduled_emailCancels a scheduled email that has not gone out yet.POST /emails/{id}/cancelfull access
setup_sending_domainMakes a domain ready to send through the company's connected DNS provider. See Automatic setup.POST /domains/setupfull access, created by the company owner
list_domainsThe company's domains and whether each is ready to send.GET /domainsfull access
list_suppressionsAddresses mail is no longer sent to.GET /suppressionsfull access
  • send_email takes the fields of POST /emails (from, to, subject, html, text, cc, bcc, reply_to, scheduled_at, tags, attachments) and idempotency_key in place of the header: 1 to 256 printable ASCII characters without spaces. Use it whenever the agent may retry, so a retry never sends twice.
  • One MCP request may be at most 1 MB, so attachments and bodies together stay under about 700 KB per call. Send larger attachments through the REST API.
  • The list tools take limit (1 to 100), after and before, as in pagination.
  • list_email_events leaves out the opener's IP address and browser string. Text that comes from recipients and remote mail servers, such as bounce reasons and subjects, is marked for the agent as data, never as instructions.
  • setup_sending_domain changes the domain's live DNS: the ownership record, SPF (merged into the existing record) and DKIM. It never changes MX, DMARC or any other record, and every change raises an alert for the company in the console.

Results and errors

A tool returns the endpoint's JSON response, as text and as structuredContent. When the endpoint answers with an error, isError is true and the result is the API's usual { statusCode, name, message } (see Errors); a 429 also carries retry_after in seconds.

cURL
curl https://send.tsmart.ai/mcp \
  -H "Authorization: Bearer $TSMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "send_email",
      "arguments": {
        "from": "Acme <no-reply@acme.com>",
        "to": "jane@example.com",
        "subject": "Your order has shipped",
        "text": "Your order is on its way.",
        "idempotency_key": "order-1042-shipped"
      }
    }
  }'
200 OK
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "{\n  \"id\": \"4ef9a417-02e9-4d39-ad75-9611e0fa6f60\"\n}" }
    ],
    "structuredContent": { "id": "4ef9a417-02e9-4d39-ad75-9611e0fa6f60" },
    "isError": false
  }
}

A request that is refused before any tool runs, because the key is missing or unknown, the request rate is exceeded or the body is too large, is answered with the same HTTP status as the REST API and a JSON-RPC error. A 401 carries WWW-Authenticate: Bearer, a 429 carries retry-after.

Protocol

  • Transport: Streamable HTTP, stateless. Each POST carries one JSON-RPC request and is answered with JSON. There is no session and no event stream: GET answers 405.
  • Protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.
  • Notifications are answered with 202 and no body. Batched JSON-RPC requests are not supported.
  • A request with an Origin header from another site is refused with 403, so a web page cannot drive an agent's session.

Limits and logs

Each MCP request counts as one request against the company's request rate and requests in progress; the tool's own endpoint call is not counted again. Sending through send_email counts against the same hourly and monthly limits as the REST API. Under tsmartSend → Logs the MCP request appears as /mcp, and each tool call as the endpoint it used, with a user agent that ends in tsmart-mcp/1.0.