SPINE Developer API

One platform API for external projects: mail, SSL certificates, DNS, mailboxes, domains, webhooks and Telegram bots, all under a single key.

BASE · https://api.spine.maxsystems.az

🔑 Authentication

The Authorization: Bearer spine_sk_… header in every request. The key is issued in the console, shown once, and revoked in one click.

⚙️ Metering and limits

Each key counts requests; the default limit is 120/min (configurable). On overflow, 429. Daily/monthly quotas are optional.

⚠️ Error codes

401 invalid key · 403 missing scope · 429 rate limit · 400 bad request (the error field).

Permissions (scopes)

Scope	What it allows
`mail:send`	Sending emails
`mail:read`	Reading emails from your mailboxes
`mail:mailboxes`	Creating and managing mailboxes
`mail:domains`	Connecting domains and their status
`cert:issue`	Ordering and reissuing certificates
`cert:read`	Certificate status and download
`dns:read`	Reading the zone DNS records
`dns:records`	Managing the zone DNS records
`webhooks`	Subscribing to webhooks (incoming emails, delivery events)
`telegram:bots`	Managing the project Telegram bots
`webmail:login`	Employee auto-login links to webmail (SSO for embedding)

Mail

POST/v1/mail/sendmail:send

Send an email. The sender domain must be connected to SPINE mail and belong to the project.

Parameters

`from`	sender address (required)
`to`	recipient (required)
`subject`	subject (or template)
`text / html`	email body
`category`	label for statistics (optional)
`idempotencyKey`	duplicate protection (optional)

Request body

{
  "from": "noreply@ваш-домен",
  "to": "user@example.com",
  "subject": "Привет",
  "text": "Тело письма"
}

Response example

{ "id": "01K…", "status": "sent", "relayMessageId": "…" }

Code examples

curl -X POST "https://api.spine.maxsystems.az/v1/mail/send" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"noreply@ваш-домен","to":"user@example.com","subject":"Привет","text":"Тело письма"}'

const res = await fetch("https://api.spine.maxsystems.az/v1/mail/send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "from": "noreply@ваш-домен",
  "to": "user@example.com",
  "subject": "Привет",
  "text": "Тело письма"
})
});
const data = await res.json();

import requests

r = requests.post(
  "https://api.spine.maxsystems.az/v1/mail/send",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY", "Content-Type": "application/json"},
  data='''{"from":"noreply@ваш-домен","to":"user@example.com","subject":"Привет","text":"Тело письма"}'''
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/mail/send");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{"from":"noreply@ваш-домен","to":"user@example.com","subject":"Привет","text":"Тело письма"}',
]);
$data = json_decode(curl_exec($ch), true);

Certificates

POST/v1/certs/issuecert:issue

Order an SSL certificate for a domain in a managed zone. Issued in ~15–30 sec.

Parameters

`domains`	list of domains, wildcard *.domain allowed (required)
`csr`	your own CSR, then the private key stays with you (optional)
`autoRenew`	auto-renewal, true by default

Request body

{ "domains": ["app.ваш-домен", "*.ваш-домен"], "autoRenew": true }

Response example

{ "id": "…", "subject": "app.ваш-домен", "sans": [...], "status": "pending" }

Code examples

curl -X POST "https://api.spine.maxsystems.az/v1/certs/issue" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains":["app.ваш-домен","*.ваш-домен"],"autoRenew":true}'

const res = await fetch("https://api.spine.maxsystems.az/v1/certs/issue", {
  method: "POST",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ "domains": ["app.ваш-домен", "*.ваш-домен"], "autoRenew": true })
});
const data = await res.json();

import requests

r = requests.post(
  "https://api.spine.maxsystems.az/v1/certs/issue",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY", "Content-Type": "application/json"},
  data='''{"domains":["app.ваш-домен","*.ваш-домен"],"autoRenew":true}'''
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/certs/issue");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{"domains":["app.ваш-домен","*.ваш-домен"],"autoRenew":true}',
]);
$data = json_decode(curl_exec($ch), true);

GET/v1/certs/{id}/statuscert:read

Certificate status (pending → active | failed).

Response example

{ "status": "active", "notAfter": "…", "daysLeft": 89 }

Code examples

curl -X GET "https://api.spine.maxsystems.az/v1/certs/{id}/status" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/certs/{id}/status", {
  method: "GET",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.get(
  "https://api.spine.maxsystems.az/v1/certs/{id}/status",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/certs/{id}/status");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

GET/v1/certs/{id}/downloadcert:read

Download the certificate (fullchain + private key; for CSR-based certs privkey=null).

Response example

{ "fullchain": "-----BEGIN CERTIFICATE-----…", "privkey": "…" }

Code examples

curl -X GET "https://api.spine.maxsystems.az/v1/certs/{id}/download" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/certs/{id}/download", {
  method: "GET",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.get(
  "https://api.spine.maxsystems.az/v1/certs/{id}/download",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/certs/{id}/download");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

Mailboxes

POST/v1/mailboxesmail:mailboxes

Create a mailbox on your own domain.

Parameters

`name`	mailbox name before @ (2–40, [a-z0-9._-])
`domain`	project domain (required)
`password`	mailbox password (min. 8)
`description`	description (optional)

Request body

{ "name": "info", "domain": "ваш-домен", "password": "…" }

Response example

{ "email": "info@ваш-домен", "id": "…" }

Code examples

curl -X POST "https://api.spine.maxsystems.az/v1/mailboxes" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"info","domain":"ваш-домен","password":"…"}'

const res = await fetch("https://api.spine.maxsystems.az/v1/mailboxes", {
  method: "POST",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ "name": "info", "domain": "ваш-домен", "password": "…" })
});
const data = await res.json();

import requests

r = requests.post(
  "https://api.spine.maxsystems.az/v1/mailboxes",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY", "Content-Type": "application/json"},
  data='''{"name":"info","domain":"ваш-домен","password":"…"}'''
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/mailboxes");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{"name":"info","domain":"ваш-домен","password":"…"}',
]);
$data = json_decode(curl_exec($ch), true);

GET/v1/mailboxesmail:mailboxes

List of mailboxes and groups on the project domains. The type field: personal, shared (several people have access), group (distribution group). Groups have a membersCount field.

Response example

{ "mailboxes": [ { "id": "…", "email": "ivan@ваш-домен", "type": "personal", "usedBytes": 0 }, { "id": "…", "email": "team@ваш-домен", "type": "group", "membersCount": 4 } ] }

Code examples

curl -X GET "https://api.spine.maxsystems.az/v1/mailboxes" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/mailboxes", {
  method: "GET",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.get(
  "https://api.spine.maxsystems.az/v1/mailboxes",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/mailboxes");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

DELETE/v1/mailboxes/{id}mail:mailboxes

Delete a mailbox (only on your own domain).

Response example

{ "deleted": true }

Code examples

curl -X DELETE "https://api.spine.maxsystems.az/v1/mailboxes/{id}" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/mailboxes/{id}", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.delete(
  "https://api.spine.maxsystems.az/v1/mailboxes/{id}",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/mailboxes/{id}");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

POST/v1/mailboxes/{id}/sharedmail:mailboxes

Mark a mailbox as shared or remove the mark. A shared mailbox is a personal mailbox that several people are given access to (support@, info@). Changes the mailbox type field.

Request body

{ "shared": true }

Response example

{ "id": "…", "shared": true }

Code examples

curl -X POST "https://api.spine.maxsystems.az/v1/mailboxes/{id}/shared" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shared":true}'

const res = await fetch("https://api.spine.maxsystems.az/v1/mailboxes/{id}/shared", {
  method: "POST",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ "shared": true })
});
const data = await res.json();

import requests

r = requests.post(
  "https://api.spine.maxsystems.az/v1/mailboxes/{id}/shared",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY", "Content-Type": "application/json"},
  data='''{"shared":true}'''
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/mailboxes/{id}/shared");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{"shared":true}',
]);
$data = json_decode(curl_exec($ch), true);

GET/v1/mailboxes/{id}/messagesmail:read

List of the latest emails in a mailbox (newest first). You can filter by address, handy for a contact conversation panel.

Parameters

`limit`	how many emails to return, up to 100 (20 by default)
`with`	contact address: emails FROM or TO them (conversation with a counterparty)
`from`	filter by sender (address substring)
`to`	filter by recipient (address substring)

Response example

{ "messages": [ { "id": "eaaaaab", "messageId": ["<abc@bank.az>"], "subject": "…", "from": [{"email":"…"}], "receivedAt": "…", "preview": "…" } ] }

Code examples

curl -X GET "https://api.spine.maxsystems.az/v1/mailboxes/{id}/messages" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/mailboxes/{id}/messages", {
  method: "GET",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.get(
  "https://api.spine.maxsystems.az/v1/mailboxes/{id}/messages",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/mailboxes/{id}/messages");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

GET/v1/mailboxes/{id}/messages/{msgId}mail:read

The full email: body, RFC Message-ID/In-Reply-To/References (for threading) and raw headers. Note: the id in the path is per-mailbox (not global); the global key is messageId.

Response example

{ "id": "eaaaaab", "messageId": "<abc@bank.az>", "inReplyTo": ["<prev@you.az>"], "references": ["<root@…>"], "subject": "…", "from": […], "to": […], "receivedAt": "…", "text": "тело письма", "headers": [{"name":"Message-ID","value":"<abc@bank.az>"}, …] }

Code examples

curl -X GET "https://api.spine.maxsystems.az/v1/mailboxes/{id}/messages/{msgId}" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/mailboxes/{id}/messages/{msgId}", {
  method: "GET",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.get(
  "https://api.spine.maxsystems.az/v1/mailboxes/{id}/messages/{msgId}",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/mailboxes/{id}/messages/{msgId}");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

Groups

GET/v1/groupsmail:mailboxes

List of the project distribution groups. A group is an address team@domain; an email sent to it fans out to all members in their personal mailboxes.

Response example

{ "groups": [ { "id": "…", "email": "team@ваш-домен", "membersCount": 4 } ] }

Code examples

curl -X GET "https://api.spine.maxsystems.az/v1/groups" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/groups", {
  method: "GET",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.get(
  "https://api.spine.maxsystems.az/v1/groups",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/groups");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

POST/v1/groupsmail:mailboxes

Create a distribution group name@domain. The domain must belong to your project.

Parameters

`domain`	project domain (required)
`name`	address name, 2-40 characters [a-z0-9._-] (required)
`description`	group description (optional)

Request body

{ "domain": "ваш-домен.az", "name": "team", "description": "Вся команда" }

Response example

{ "id": "…", "email": "team@ваш-домен.az" }

Code examples

curl -X POST "https://api.spine.maxsystems.az/v1/groups" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"ваш-домен.az","name":"team","description":"Вся команда"}'

const res = await fetch("https://api.spine.maxsystems.az/v1/groups", {
  method: "POST",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ "domain": "ваш-домен.az", "name": "team", "description": "Вся команда" })
});
const data = await res.json();

import requests

r = requests.post(
  "https://api.spine.maxsystems.az/v1/groups",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY", "Content-Type": "application/json"},
  data='''{"domain":"ваш-домен.az","name":"team","description":"Вся команда"}'''
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/groups");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{"domain":"ваш-домен.az","name":"team","description":"Вся команда"}',
]);
$data = json_decode(curl_exec($ch), true);

DELETE/v1/groups/{id}mail:mailboxes

Delete a group.

Response example

{ "deleted": true }

Code examples

curl -X DELETE "https://api.spine.maxsystems.az/v1/groups/{id}" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/groups/{id}", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.delete(
  "https://api.spine.maxsystems.az/v1/groups/{id}",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/groups/{id}");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

GET/v1/groups/{id}/membersmail:mailboxes

Group members (mailboxes the mail fans out to).

Response example

{ "members": [ { "id": "…", "email": "ivan@ваш-домен.az" } ] }

Code examples

curl -X GET "https://api.spine.maxsystems.az/v1/groups/{id}/members" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/groups/{id}/members", {
  method: "GET",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.get(
  "https://api.spine.maxsystems.az/v1/groups/{id}/members",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/groups/{id}/members");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

POST/v1/groups/{id}/membersmail:mailboxes

Add a mailbox to the group by its address.

Request body

{ "mailbox": "ivan@ваш-домен.az" }

Response example

{ "ok": true, "member": { "id": "…", "email": "ivan@ваш-домен.az" } }

Code examples

curl -X POST "https://api.spine.maxsystems.az/v1/groups/{id}/members" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mailbox":"ivan@ваш-домен.az"}'

const res = await fetch("https://api.spine.maxsystems.az/v1/groups/{id}/members", {
  method: "POST",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ "mailbox": "ivan@ваш-домен.az" })
});
const data = await res.json();

import requests

r = requests.post(
  "https://api.spine.maxsystems.az/v1/groups/{id}/members",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY", "Content-Type": "application/json"},
  data='''{"mailbox":"ivan@ваш-домен.az"}'''
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/groups/{id}/members");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{"mailbox":"ivan@ваш-домен.az"}',
]);
$data = json_decode(curl_exec($ch), true);

DELETE/v1/groups/{id}/members/{userId}mail:mailboxes

Remove a member from the group.

Response example

{ "ok": true }

Code examples

curl -X DELETE "https://api.spine.maxsystems.az/v1/groups/{id}/members/{userId}" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/groups/{id}/members/{userId}", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.delete(
  "https://api.spine.maxsystems.az/v1/groups/{id}/members/{userId}",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/groups/{id}/members/{userId}");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

Webmail (SSO)

POST/v1/webmail/login-linkwebmail:login

Issue an employee a one-time auto-login link to THEIR own webmail mailbox, so you can embed mail into your app (e.g. a CRM). The link lives 60 seconds and is single-use: on opening it (in a new tab or in an iframe) the employee lands in mail without a second login. The mailbox must be on your domain.

Parameters

mailbox the employee full mailbox address on your domain (required)

Request body

{ "mailbox": "ivan@ваш-домен.az" }

Response example

{ "url": "https://webmail.ваш-домен.az/?login_token=…", "email": "ivan@ваш-домен.az", "expiresIn": 60 }

Code examples

curl -X POST "https://api.spine.maxsystems.az/v1/webmail/login-link" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mailbox":"ivan@ваш-домен.az"}'

const res = await fetch("https://api.spine.maxsystems.az/v1/webmail/login-link", {
  method: "POST",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ "mailbox": "ivan@ваш-домен.az" })
});
const data = await res.json();

import requests

r = requests.post(
  "https://api.spine.maxsystems.az/v1/webmail/login-link",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY", "Content-Type": "application/json"},
  data='''{"mailbox":"ivan@ваш-домен.az"}'''
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/webmail/login-link");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{"mailbox":"ivan@ваш-домен.az"}',
]);
$data = json_decode(curl_exec($ch), true);

Domains

POST/v1/maildomainsmail:domains

Connect a domain to mail (creates the domain and, when possible, publishes DNS itself).

Request body

{ "name": "ваш-домен" }

Response example

{ "id": "…", "name": "ваш-домен", "autoDns": { "created": 6 }, "records": [...], "ready": false }

Code examples

curl -X POST "https://api.spine.maxsystems.az/v1/maildomains" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"ваш-домен"}'

const res = await fetch("https://api.spine.maxsystems.az/v1/maildomains", {
  method: "POST",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ "name": "ваш-домен" })
});
const data = await res.json();

import requests

r = requests.post(
  "https://api.spine.maxsystems.az/v1/maildomains",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY", "Content-Type": "application/json"},
  data='''{"name":"ваш-домен"}'''
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/maildomains");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{"name":"ваш-домен"}',
]);
$data = json_decode(curl_exec($ch), true);

GET/v1/maildomainsmail:domains

List of the project connected domains.

Response example

{ "domains": [ { "id": "…", "name": "ваш-домен" } ] }

Code examples

curl -X GET "https://api.spine.maxsystems.az/v1/maildomains" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/maildomains", {
  method: "GET",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.get(
  "https://api.spine.maxsystems.az/v1/maildomains",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/maildomains");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

GET/v1/maildomains/{domain}mail:domains

DNS records and the domain verification status.

Response example

{ "name": "ваш-домен", "records": [...], "ready": true }

Code examples

curl -X GET "https://api.spine.maxsystems.az/v1/maildomains/{domain}" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/maildomains/{domain}", {
  method: "GET",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.get(
  "https://api.spine.maxsystems.az/v1/maildomains/{domain}",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/maildomains/{domain}");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

DNS

GET/v1/dns/{zone}/recordsdns:read

List of the zone DNS records (the zone must be linked to the project).

Response example

{ "zone": "ваш-домен", "records": [ { "id": "…", "type": "A", "name": "@", "data": "1.2.3.4" } ] }

Code examples

curl -X GET "https://api.spine.maxsystems.az/v1/dns/{zone}/records" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/dns/{zone}/records", {
  method: "GET",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.get(
  "https://api.spine.maxsystems.az/v1/dns/{zone}/records",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/dns/{zone}/records");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

POST/v1/dns/{zone}/recordsdns:records

Create a DNS record in the project zone.

Parameters

`type`	A \| AAAA \| TXT \| MX \| CNAME \| NS \| SRV \| CAA
`name`	record name ('@' for the root)
`data`	value
`priority / ttl`	for MX / TTL (optional)

Request body

{ "type": "CNAME", "name": "app", "data": "target.example.com" }

Response example

{ "created": true }

Code examples

curl -X POST "https://api.spine.maxsystems.az/v1/dns/{zone}/records" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"CNAME","name":"app","data":"target.example.com"}'

const res = await fetch("https://api.spine.maxsystems.az/v1/dns/{zone}/records", {
  method: "POST",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ "type": "CNAME", "name": "app", "data": "target.example.com" })
});
const data = await res.json();

import requests

r = requests.post(
  "https://api.spine.maxsystems.az/v1/dns/{zone}/records",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY", "Content-Type": "application/json"},
  data='''{"type":"CNAME","name":"app","data":"target.example.com"}'''
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/dns/{zone}/records");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{"type":"CNAME","name":"app","data":"target.example.com"}',
]);
$data = json_decode(curl_exec($ch), true);

DELETE/v1/dns/{zone}/records/{id}dns:records

Delete a DNS record. For GoDaddy add ?data=<value>.

Response example

{ "deleted": true }

Code examples

curl -X DELETE "https://api.spine.maxsystems.az/v1/dns/{zone}/records/{id}" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/dns/{zone}/records/{id}", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.delete(
  "https://api.spine.maxsystems.az/v1/dns/{zone}/records/{id}",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/dns/{zone}/records/{id}");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

Webhooks

POST/v1/webhookswebhooks

Subscribe to events: the platform will send a POST to your URL. The secret in the response is shown once.

Parameters

`url`	your https receiving address (required)
`events`	mail.received, mail.delivered, mail.bounced, mail.complained

Request body

{ "url": "https://ваш-сервер/webhook", "events": ["mail.received", "mail.bounced"] }

Response example

{ "id": "…", "url": "…", "events": [...], "secret": "whsec_…" }

Code examples

curl -X POST "https://api.spine.maxsystems.az/v1/webhooks" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://ваш-сервер/webhook","events":["mail.received","mail.bounced"]}'

const res = await fetch("https://api.spine.maxsystems.az/v1/webhooks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ "url": "https://ваш-сервер/webhook", "events": ["mail.received", "mail.bounced"] })
});
const data = await res.json();

import requests

r = requests.post(
  "https://api.spine.maxsystems.az/v1/webhooks",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY", "Content-Type": "application/json"},
  data='''{"url":"https://ваш-сервер/webhook","events":["mail.received","mail.bounced"]}'''
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/webhooks");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{"url":"https://ваш-сервер/webhook","events":["mail.received","mail.bounced"]}',
]);
$data = json_decode(curl_exec($ch), true);

GET/v1/webhookswebhooks

List of your webhooks.

Response example

{ "webhooks": [ { "id": "…", "url": "…", "events": [...], "active": true } ] }

Code examples

curl -X GET "https://api.spine.maxsystems.az/v1/webhooks" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/webhooks", {
  method: "GET",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.get(
  "https://api.spine.maxsystems.az/v1/webhooks",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/webhooks");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

DELETE/v1/webhooks/{id}webhooks

Delete a webhook.

Response example

{ "deleted": true }

Code examples

curl -X DELETE "https://api.spine.maxsystems.az/v1/webhooks/{id}" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/webhooks/{id}", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.delete(
  "https://api.spine.maxsystems.az/v1/webhooks/{id}",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/webhooks/{id}");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

GET/v1/webhooks/{id}/deliverieswebhooks

Webhook delivery log: status (pending/delivered/failed), codes, attempts and the exact signed body, handy for debugging the signature.

Response example

{ "deliveries": [ { "id": 42, "event": "mail.received", "status": "failed", "httpCode": 401, "attempts": 7, "payload": "{…}" } ] }

Code examples

curl -X GET "https://api.spine.maxsystems.az/v1/webhooks/{id}/deliveries" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/webhooks/{id}/deliveries", {
  method: "GET",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.get(
  "https://api.spine.maxsystems.az/v1/webhooks/{id}/deliveries",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/webhooks/{id}/deliveries");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

POST/v1/webhooks/{id}/deliveries/{deliveryId}/redeliverwebhooks

Redeliver a specific delivery now (for example, after you have fixed the signature verifier).

Response example

{ "status": "delivered", "httpCode": 200 }

Code examples

curl -X POST "https://api.spine.maxsystems.az/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver", {
  method: "POST",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.post(
  "https://api.spine.maxsystems.az/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

Telegram bots

POST/v1/telegram/mybotstelegram:bots

Connect an existing bot to the platform by its token (from BotFather).

Request body

{ "token": "123456:ABC-…", "note": "бот проекта" }

Response example

{ "id": "…", "botId": 123456, "username": "MyBot", "name": "My Bot" }

Code examples

curl -X POST "https://api.spine.maxsystems.az/v1/telegram/mybots" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"123456:ABC-…","note":"бот проекта"}'

const res = await fetch("https://api.spine.maxsystems.az/v1/telegram/mybots", {
  method: "POST",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ "token": "123456:ABC-…", "note": "бот проекта" })
});
const data = await res.json();

import requests

r = requests.post(
  "https://api.spine.maxsystems.az/v1/telegram/mybots",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY", "Content-Type": "application/json"},
  data='''{"token":"123456:ABC-…","note":"бот проекта"}'''
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/telegram/mybots");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{"token":"123456:ABC-…","note":"бот проекта"}',
]);
$data = json_decode(curl_exec($ch), true);

POST/v1/telegram/mybots/bulktelegram:bots

Bulk import: connect many bots at once from a list of tokens (from BotFather). tokens is an array or text (one token per line).

Request body

{ "tokens": ["123456:AAA…", "234567:BBB…"] }

Response example

{ "total": 2, "added": 2, "failed": 0, "results": [ { "ok": true, "username": "MyBot", "botId": 123456 } ] }

Code examples

curl -X POST "https://api.spine.maxsystems.az/v1/telegram/mybots/bulk" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tokens":["123456:AAA…","234567:BBB…"]}'

const res = await fetch("https://api.spine.maxsystems.az/v1/telegram/mybots/bulk", {
  method: "POST",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ "tokens": ["123456:AAA…", "234567:BBB…"] })
});
const data = await res.json();

import requests

r = requests.post(
  "https://api.spine.maxsystems.az/v1/telegram/mybots/bulk",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY", "Content-Type": "application/json"},
  data='''{"tokens":["123456:AAA…","234567:BBB…"]}'''
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/telegram/mybots/bulk");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{"tokens":["123456:AAA…","234567:BBB…"]}',
]);
$data = json_decode(curl_exec($ch), true);

GET/v1/telegram/mybotstelegram:bots

List of the project bots.

Response example

{ "bots": [ { "id": "…", "username": "MyBot", "webhookSet": true } ] }

Code examples

curl -X GET "https://api.spine.maxsystems.az/v1/telegram/mybots" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/telegram/mybots", {
  method: "GET",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.get(
  "https://api.spine.maxsystems.az/v1/telegram/mybots",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/telegram/mybots");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

GET/v1/telegram/mybots/{id}telegram:bots

Live bot status (getMe + webhook + commands).

Response example

{ "username": "MyBot", "me": {...}, "webhook": {...}, "commands": [...] }

Code examples

curl -X GET "https://api.spine.maxsystems.az/v1/telegram/mybots/{id}" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/telegram/mybots/{id}", {
  method: "GET",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.get(
  "https://api.spine.maxsystems.az/v1/telegram/mybots/{id}",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/telegram/mybots/{id}");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

POST/v1/telegram/mybots/{id}/webhooktelegram:bots

Route the bot updates to your server (SPINE receives them from Telegram and forwards them to you).

Request body

{ "forwardUrl": "https://ваш-сервер/tg" }

Response example

{ "hookUrl": "https://api.spine.maxsystems.az/v1/tg/hook/123456", "forwardUrl": "…" }

Code examples

curl -X POST "https://api.spine.maxsystems.az/v1/telegram/mybots/{id}/webhook" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"forwardUrl":"https://ваш-сервер/tg"}'

const res = await fetch("https://api.spine.maxsystems.az/v1/telegram/mybots/{id}/webhook", {
  method: "POST",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ "forwardUrl": "https://ваш-сервер/tg" })
});
const data = await res.json();

import requests

r = requests.post(
  "https://api.spine.maxsystems.az/v1/telegram/mybots/{id}/webhook",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY", "Content-Type": "application/json"},
  data='''{"forwardUrl":"https://ваш-сервер/tg"}'''
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/telegram/mybots/{id}/webhook");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{"forwardUrl":"https://ваш-сервер/tg"}',
]);
$data = json_decode(curl_exec($ch), true);

GET/v1/telegram/mypresetstelegram:bots

Turnkey factory presets available to the project (shared + your own): commands, webhook, profile.

Response example

{ "presets": [ { "id": "…", "name": "Поддержка", "forwardUrl": "https://…" } ] }

Code examples

curl -X GET "https://api.spine.maxsystems.az/v1/telegram/mypresets" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY"

const res = await fetch("https://api.spine.maxsystems.az/v1/telegram/mypresets", {
  method: "GET",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY"
  }
});
const data = await res.json();

import requests

r = requests.get(
  "https://api.spine.maxsystems.az/v1/telegram/mypresets",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY"}
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/telegram/mypresets");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY"],
]);
$data = json_decode(curl_exec($ch), true);

POST/v1/telegram/mybots/create-linktelegram:bots

Factory: a deep link to create a new bot. The user confirms in Telegram and the bot connects to the project by itself. With presetId the bot is deployed turnkey right away (commands + webhook + profile).

Request body

{ "suggestedUsername": "myproject_bot", "presetId": "…(необязательно)" }

Response example

{ "link": "https://t.me/newbot/spinemsbot/myproject_bot" }

Code examples

curl -X POST "https://api.spine.maxsystems.az/v1/telegram/mybots/create-link" \
  -H "Authorization: Bearer spine_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"suggestedUsername":"myproject_bot","presetId":"…(необязательно)"}'

const res = await fetch("https://api.spine.maxsystems.az/v1/telegram/mybots/create-link", {
  method: "POST",
  headers: {
    "Authorization": "Bearer spine_sk_YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ "suggestedUsername": "myproject_bot", "presetId": "…(необязательно)" })
});
const data = await res.json();

import requests

r = requests.post(
  "https://api.spine.maxsystems.az/v1/telegram/mybots/create-link",
  headers={"Authorization": "Bearer spine_sk_YOUR_KEY", "Content-Type": "application/json"},
  data='''{"suggestedUsername":"myproject_bot","presetId":"…(необязательно)"}'''
)
print(r.status_code, r.json())

$ch = curl_init("https://api.spine.maxsystems.az/v1/telegram/mybots/create-link");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spine_sk_YOUR_KEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{"suggestedUsername":"myproject_bot","presetId":"…(необязательно)"}',
]);
$data = json_decode(curl_exec($ch), true);

WEBHOOKSignature verification and delivery

Every delivery is a POST with the headers X-Spine-Event (event type) and X-Spine-Signature: sha256=<hex>. Body: {"event":"…","ts":"…","data":{…}}.

The signature = HMAC-SHA256 of the raw request body (bytes as received, before parsing JSON). The key is the whsec_… secret as is, the whole string: do NOT base64-decode it and do NOT strip the prefix (this is not Svix). The result is hex, with the sha256= prefix. Compare in constant time.

Verifier (Node.js)

const crypto = require("crypto");
function verifySpineWebhook(secret, rawBody, sigHeader) {
  // secret   — строка ЦЕЛИКОМ, включая префикс whsec_ (не декодировать/не обрезать)
  // rawBody  — СЫРОЕ тело запроса (Buffer/строка), до JSON.parse
  // sigHeader— значение заголовка X-Spine-Signature ("sha256=…")
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(sigHeader || ""), b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Delivery and retries

One immediate attempt; on failure, durable retries with exponential backoff (≈ after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, up to 7 attempts over ~21 hours); the queue survives a restart. Success = your 2xx response. Delivery log: GET /v1/webhooks/{id}/deliveries (shows status, codes and the exact signed body); redeliver a specific one: POST /v1/webhooks/{id}/deliveries/{deliveryId}/redeliver. Respond quickly and push heavy work to the background (delivery is at-least-once, so make your handler idempotent).

The mail.received event: what is inside data

For an incoming email we return its metadata (message), the thread RFC headers (rfc) and fraud signals (security):

"data": {
  "mailbox": "you@ваш-домен.az", "mailboxId": "c",
  "message": {
    "id": "eaaaaab",                          // per-mailbox id (НЕ глобальный, см. ниже)
    "from": [{ "email": "sender@bank.az" }], "to": [{ "email": "you@ваш-домен.az" }],
    "subject": "…", "receivedAt": "…", "preview": "…"
  },
  "rfc": {
    "messageId": "<abc123@bank.az>",         // RFC Message-ID — глобально-уникальный ключ письма
    "inReplyTo": ["<prev@you.az>"],           // на что это ответ
    "references": ["<root@…>", "<prev@you.az>"]  // цепочка треда
  },
  "security": {
    "spam": { "isSpam": false, "score": 2.9, "status": "No", "label": "ham", "symbols": "DKIM_VALID(-0.5), …" },
    "auth": { "spf": "pass", "dkim": "pass", "dmarc": "pass" }
  }
}

Identifiers: message.id is a short per-mailbox id (to read the same email via the API), NOT global. As a globally unique key (idempotency, threading) use rfc.messageId; link replies into a thread by rfc.inReplyTo/rfc.references.

security: score is the spam-filter score (rspamd style; higher = more suspicious), isSpam is whether it crossed the threshold; spf/dkim/dmarc are the sender authenticity (pass/fail/none…). If the email has no such headers, the field may be null.

SPINE API · base address https://api.spine.maxsystems.az · machine description /v1/openapi.json