Sentroy API

Complete reference for the Sentroy platform REST API.

Authentication

All API requests require a Bearer access token in the Authorization header. Create tokens from Admin → Access Tokens in your Sentroy dashboard.

Base URL (for cURL / raw HTTP)

https://sentroy.com/api/companies/{company-slug}

Replace {company-slug} with your company slug in all cURL endpoints below.

SDKs only need https://sentroy.com as the base URL — the /api/companies/{slug} path is built automatically from your companySlug config.

Quick Start

import { Sentroy } from "@sentroy-co/client-sdk"

const sentroy = new Sentroy({
  baseUrl: "https://sentroy.com",
  companySlug: "my-company",
  accessToken: "stk_...",
})

import sentroy "github.com/Sentroy-Co/client-sdk/go"

client := sentroy.New(sentroy.Config{
    BaseURL:     "https://sentroy.com",
    CompanySlug: "my-company",
    AccessToken: "stk_...",
})

from sentroy import Sentroy

sentroy = Sentroy(
    base_url="https://sentroy.com",
    company_slug="my-company",
    access_token="stk_...",
)

use Sentroy\ClientSdk\Sentroy;

$sentroy = new Sentroy([
    'base_url'      => 'https://sentroy.com',
    'company_slug' => 'my-company',
    'access_token' => 'stk_...',
]);

SDKs

TypeScript / Node.js npm i @sentroy-co/client-sdk Go go get ...client-sdk/go Python pip install sentroy-client-sdk PHP composer require sentroy-co/client-sdk

For AI Agents

Plain-text documentation for LLM consumption:

SDK	Raw URL
TypeScript	`typescript/README.md`
Go	`go/README.md`
Python	`python/README.md`
PHP	`php/README.md`
cURL	`curl/README.md`

Error Handling

Error responses use a consistent envelope:

{
  "data": null,
  "error": "Human-readable error message"
}

Status	Meaning
`400`	Bad request — missing or invalid parameters
`401`	Invalid or expired access token
`403`	Insufficient permissions or token/company mismatch
`404`	Resource not found
`500`	Internal server error

Domains

List domains

GET /domains

curl -s https://sentroy.com/api/companies/{company-slug}/domains \
  -H "Authorization: Bearer stk_..."

const domains = await sentroy.domains.list()

Response

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "domain": "example.com",
      "status": "active",
      "spfVerified": true,
      "dkimVerified": true,
      "dmarcVerified": true,
      "createdAt": "2026-01-10T08:00:00.000Z",
      "updatedAt": "2026-01-10T09:15:00.000Z"
    }
  ]
}

Get domain

GET /domains/{id}

curl -s https://sentroy.com/api/companies/{company-slug}/domains/{domain-id} \
  -H "Authorization: Bearer stk_..."

const domain = await sentroy.domains.get("domain-id")

Mailboxes

List mailbox accounts

GET /mailboxes

curl -s https://sentroy.com/api/companies/{company-slug}/mailboxes \
  -H "Authorization: Bearer stk_..."

const mailboxes = await sentroy.mailboxes.list()

Response

{
  "data": [
    {
      "email": "info@example.com",
      "domain": "example.com",
      "username": "info"
    }
  ]
}

Templates

List templates

GET /templates

curl -s https://sentroy.com/api/companies/{company-slug}/templates \
  -H "Authorization: Bearer stk_..."

const templates = await sentroy.templates.list()

Get template

GET /templates/{id}

curl -s https://sentroy.com/api/companies/{company-slug}/templates/{template-id} \
  -H "Authorization: Bearer stk_..."

const template = await sentroy.templates.get("template-id")

Response

{
  "data": {
    "id": "b3f1a2c4-...",
    "name": { "en": "Welcome Email", "tr": "Hosgeldin E-postasi" },
    "subject": { "en": "Welcome, {{name}}!", "tr": "Hosgeldin, {{name}}!" },
    "mjmlBody": { "en": "<mjml>...</mjml>", "tr": "<mjml>...</mjml>" },
    "variables": ["name", "company"],
    "domainId": "a1b2c3d4-...",
    "domainName": "example.com",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-04-10T14:22:00.000Z"
  }
}

Fields like name, subject, and mjmlBody can be a plain string or an object keyed by language code. Use the variables array to know which {{placeholders}} the template expects.

Send Email

POST /send

Send with a template

curl -s -X POST https://sentroy.com/api/companies/{company-slug}/send \
  -H "Authorization: Bearer stk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "from": "info@example.com",
    "subject": "Welcome!",
    "domainId": "a1b2c3d4-...",
    "templateId": "b3f1a2c4-...",
    "variables": { "name": "John", "company": "Acme" }
  }'

const result = await sentroy.send.email({
  to: "user@example.com",
  from: "info@example.com",
  subject: "Welcome!",
  domainId: "a1b2c3d4-...",
  templateId: "b3f1a2c4-...",
  variables: { name: "John", company: "Acme" },
})

Send with a specific language

Use the lang parameter to select which language version of the template to render.

curl -s -X POST https://sentroy.com/api/companies/{company-slug}/send \
  -H "Authorization: Bearer stk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "from": "info@example.com",
    "subject": "Hosgeldin!",
    "domainId": "a1b2c3d4-...",
    "templateId": "b3f1a2c4-...",
    "lang": "tr",
    "variables": { "name": "Ahmet" }
  }'

const result = await sentroy.send.email({
  to: "user@example.com",
  from: "info@example.com",
  subject: "Hosgeldin!",
  domainId: "a1b2c3d4-...",
  templateId: "b3f1a2c4-...",
  lang: "tr",
  variables: { name: "Ahmet" },
})

Send with raw HTML

curl -s -X POST https://sentroy.com/api/companies/{company-slug}/send \
  -H "Authorization: Bearer stk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["user1@example.com", "user2@example.com"],
    "from": "info@example.com",
    "subject": "Hello",
    "domainId": "a1b2c3d4-...",
    "html": "<h1>Hello World</h1>"
  }'

const result = await sentroy.send.email({
  to: ["user1@example.com", "user2@example.com"],
  from: "info@example.com",
  subject: "Hello",
  domainId: "a1b2c3d4-...",
  html: "<h1>Hello World</h1>",
})

Send with attachments

curl -s -X POST https://sentroy.com/api/companies/{company-slug}/send \
  -H "Authorization: Bearer stk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "from": "info@example.com",
    "subject": "Invoice",
    "domainId": "a1b2c3d4-...",
    "html": "<p>Please find your invoice attached.</p>",
    "attachments": [{
      "filename": "invoice.pdf",
      "content": "<base64>",
      "contentType": "application/pdf"
    }]
  }'

const result = await sentroy.send.email({
  to: "user@example.com",
  from: "info@example.com",
  subject: "Invoice",
  domainId: "a1b2c3d4-...",
  html: "<p>Please find your invoice attached.</p>",
  attachments: [{
    filename: "invoice.pdf",
    content: base64String,
    contentType: "application/pdf",
  }],
})

Response

{
  "data": {
    "jobId": "job_abc123",
    "mailLogId": "log_xyz789",
    "status": "queued"
  }
}

Send parameters

Parameter	Type	Required	Description
`to`	`string \| string[]`	Yes	Recipient address(es)
`from`	`string`	Yes	Sender address (must be a verified mailbox)
`subject`	`string`	Yes	Email subject line
`domainId`	`string`	Yes	Verified domain ID
`templateId`	`string`	No	Template ID to render
`lang`	`string`	No	Template language code (e.g. `"en"`, `"tr"`)
`html`	`string`	No	Raw HTML body (used if no template)
`text`	`string`	No	Plain text body
`variables`	`object`	No	Template variable values
`cc`	`string \| string[]`	No	CC addresses
`replyTo`	`string`	No	Reply-To address
`attachments`	`array`	No	File attachments (base64)
`scheduledAt`	`string`	No	ISO 8601 datetime to schedule
`headers`	`object`	No	Custom email headers
`inReplyTo`	`string`	No	RFC 5322 Message-ID for threading
`references`	`string[]`	No	RFC 5322 References for threading

Inbox

List messages

GET /inbox

Query	Type	Description
`mailbox`	`string`	Email address of the mailbox
`folder`	`string`	IMAP folder (default: `INBOX`)
`page`	`int`	Page number
`limit`	`int`	Messages per page
`unreadOnly`	`bool`	Only return unread messages

curl -s "https://sentroy.com/api/companies/{company-slug}/inbox?mailbox=info@example.com&folder=INBOX&page=1&limit=20" \
  -H "Authorization: Bearer stk_..."

const messages = await sentroy.inbox.list({
  mailbox: "info@example.com",
  folder: "INBOX",
  page: 1,
  limit: 20,
})

Get message

GET /inbox/{uid}

curl -s "https://sentroy.com/api/companies/{company-slug}/inbox/1234?mailbox=info@example.com" \
  -H "Authorization: Bearer stk_..."

const message = await sentroy.inbox.get(1234, {
  mailbox: "info@example.com",
})

List IMAP folders

GET /inbox/mailboxes

curl -s "https://sentroy.com/api/companies/{company-slug}/inbox/mailboxes?mailbox=info@example.com" \
  -H "Authorization: Bearer stk_..."

const folders = await sentroy.inbox.listFolders("info@example.com")

Get thread by subject

GET /inbox/thread

curl -s "https://sentroy.com/api/companies/{company-slug}/inbox/thread?subject=Re%3A+Project+update&mailbox=info@example.com" \
  -H "Authorization: Bearer stk_..."

const thread = await sentroy.inbox.getThread("Re: Project update", "info@example.com")

Mark as read

POST /inbox/{uid}/read

curl -s -X POST https://sentroy.com/api/companies/{company-slug}/inbox/1234/read \
  -H "Authorization: Bearer stk_..." \
  -H "Content-Type: application/json" \
  -d '{"mailbox": "info@example.com", "folder": "INBOX"}'

await sentroy.inbox.markAsRead(1234, { mailbox: "info@example.com" })

Mark as unread

DELETE /inbox/{uid}/read

curl -s -X DELETE "https://sentroy.com/api/companies/{company-slug}/inbox/1234/read?mailbox=info@example.com&folder=INBOX" \
  -H "Authorization: Bearer stk_..."

await sentroy.inbox.markAsUnread(1234, { mailbox: "info@example.com" })

Move message

POST /inbox/{uid}/move

curl -s -X POST https://sentroy.com/api/companies/{company-slug}/inbox/1234/move \
  -H "Authorization: Bearer stk_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "Trash", "from": "INBOX", "mailbox": "info@example.com"}'

await sentroy.inbox.move(1234, "Trash", {
  from: "INBOX",
  mailbox: "info@example.com",
})

Delete message

DELETE /inbox/{uid}

curl -s -X DELETE "https://sentroy.com/api/companies/{company-slug}/inbox/1234?mailbox=info@example.com" \
  -H "Authorization: Bearer stk_..."

await sentroy.inbox.delete(1234, { mailbox: "info@example.com" })