API reference

curl -X POST https://api.mailsharks.org/v1/messages \
  -H "Authorization: Bearer ms_live_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirm" \
  -d '{
    "to": "client@example.com",
    "subject": "Заказ {{order}} принят",
    "body_html": "<p>Здравствуйте, {{name}}! Мы получили заказ {{order}}.</p>",
    "variables": {"name": "Анна", "order": "A-1042"}
  }'

import httpx

response = httpx.post(
    "https://api.mailsharks.org/v1/messages",
    headers={
        "Authorization": "Bearer ms_live_ВАШ_КЛЮЧ",
        "Idempotency-Key": "order-1042-confirm",
    },
    json={
        "to": "client@example.com",
        "subject": "Заказ {{order}} принят",
        "body_html": "<p>Здравствуйте, {{name}}! Мы получили заказ {{order}}.</p>",
        "variables": {"name": "Анна", "order": "A-1042"},
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["id"])

const response = await fetch("https://api.mailsharks.org/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ms_live_ВАШ_КЛЮЧ",
    "Content-Type": "application/json",
    "Idempotency-Key": "order-1042-confirm",
  },
  body: JSON.stringify({
    to: "client@example.com",
    subject: "Заказ {{order}} принят",
    body_html: "<p>Здравствуйте, {{name}}! Мы получили заказ {{order}}.</p>",
    variables: { name: "Анна", order: "A-1042" },
  }),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const { id } = await response.json();

# 1. Файл уезжает на Диск отправителя
curl -X POST https://api.mailsharks.org/v1/files   -H "Authorization: Bearer ms_live_ВАШ_КЛЮЧ"   -F "file=@price-2026.pdf"
# {"id": "1AbC...", "name": "price-2026.pdf", "size": 184320, "shared": true, ...}

# 2. Его номер идёт в attach — карточка встанет в конец письма
curl -X POST https://api.mailsharks.org/v1/messages   -H "Authorization: Bearer ms_live_ВАШ_КЛЮЧ"   -H "Content-Type: application/json"   -d '{
    "to": "client@example.com",
    "subject": "Прайс на 2026",
    "body_html": "<p>Прайс во вложении.</p>",
    "attach": ["1AbC..."]
  }'

import httpx

headers = {"Authorization": "Bearer ms_live_ВАШ_КЛЮЧ"}

with open("price-2026.pdf", "rb") as handle:
    uploaded = httpx.post(
        "https://api.mailsharks.org/v1/files",
        headers=headers,
        files={"file": ("price-2026.pdf", handle, "application/pdf")},
        timeout=120,
    )
uploaded.raise_for_status()

response = httpx.post(
    "https://api.mailsharks.org/v1/messages",
    headers=headers,
    json={
        "to": "client@example.com",
        "subject": "Прайс на 2026",
        "body_html": "<p>Прайс во вложении.</p>",
        "attach": [uploaded.json()["id"]],
    },
    timeout=30,
)
response.raise_for_status()

const headers = { Authorization: "Bearer ms_live_ВАШ_КЛЮЧ" };

const form = new FormData();
form.append("file", file);   // File из <input type="file"> или Blob

const uploaded = await fetch("https://api.mailsharks.org/v1/files", {
  method: "POST",
  headers,
  body: form,
}).then((r) => r.json());

await fetch("https://api.mailsharks.org/v1/messages", {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    to: "client@example.com",
    subject: "Прайс на 2026",
    body_html: "<p>Прайс во вложении.</p>",
    attach: [uploaded.id],
  }),
});

# 1. Посмотреть, какие листы и столбцы есть в таблице
curl -G https://api.mailsharks.org/v1/sheets/inspect \
  -H "Authorization: Bearer ms_live_ВАШ_КЛЮЧ" \
  --data-urlencode "link=https://docs.google.com/spreadsheets/d/1AbC.../edit"

# 2. Подключить её
curl -X POST https://api.mailsharks.org/v1/sheets \
  -H "Authorization: Bearer ms_live_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"link": "https://docs.google.com/spreadsheets/d/1AbC.../edit",
       "email_column": "email", "name_column": "name"}'

# 3. Запустить рассылку (стартует сразу)
curl -X POST https://api.mailsharks.org/v1/campaigns \
  -H "Authorization: Bearer ms_live_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"sheet_id": 42, "template_id": "a7Kd93Xz",
       "variables": {"sale": "20%"}, "daily_limit": 300}'

import httpx

api = httpx.Client(
    base_url="https://api.mailsharks.org/v1",
    headers={"Authorization": "Bearer ms_live_ВАШ_КЛЮЧ"},
    timeout=60,
)

sheet = api.post("/sheets", json={
    "link": "https://docs.google.com/spreadsheets/d/1AbC.../edit",
    "email_column": "email",
    "name_column": "name",
}).json()

campaign = api.post("/campaigns", json={
    "sheet_id": sheet["id"],
    "template_id": "a7Kd93Xz",
    "variables": {"sale": "20%"},   # общие для всех; колонки таблицы важнее
    "daily_limit": 300,
}).json()

print(campaign["id"], campaign["recipients"])

const headers = {
  "Authorization": "Bearer ms_live_ВАШ_КЛЮЧ",
  "Content-Type": "application/json",
};

const sheet = await (await fetch("https://api.mailsharks.org/v1/sheets", {
  method: "POST", headers,
  body: JSON.stringify({
    link: "https://docs.google.com/spreadsheets/d/1AbC.../edit",
    email_column: "email",
    name_column: "name",
  }),
})).json();

const campaign = await (await fetch("https://api.mailsharks.org/v1/campaigns", {
  method: "POST", headers,
  body: JSON.stringify({
    sheet_id: sheet.id,
    template_id: "a7Kd93Xz",
    variables: { sale: "20%" },
    daily_limit: 300,
  }),
})).json();

# Половине списка уйдёт тема A, половине — B
curl -X POST https://api.mailsharks.org/v1/campaigns \
  -H "Authorization: Bearer ms_live_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"sheet_id": 42, "template_id": "a7Kd93Xz",
       "variant_b": {"subject": "Три минуты вашего времени"}}'

# Кто выигрывает
curl https://api.mailsharks.org/v1/campaigns/128 \
  -H "Authorization: Bearer ms_live_ВАШ_КЛЮЧ"

# "ab": {"variants": [{"label": "A", "subject": "...",
#                      "stats": {"sent": 500, "opened": 96, ...}}, ...],
#        "verdict": {"winner": "B", "rate": {"A": 0.192, "B": 0.244},
#                    "lift": 0.271, "confidence": 0.978, "significant": true}}

import httpx

api = httpx.Client(base_url="https://api.mailsharks.org/v1",
                   headers={"Authorization": "Bearer ms_live_ВАШ_КЛЮЧ"})

campaign = api.post("/campaigns", json={
    "sheet_id": 42,
    "template_id": "a7Kd93Xz",
    # Только тема: без body_html текст письма у обоих вариантов общий.
    "variant_b": {"subject": "Три минуты вашего времени"},
}).json()

ab = api.get(f"/campaigns/{campaign['id']}").json()["ab"]
if ab["verdict"]["significant"]:
    print("Победил вариант", ab["verdict"]["winner"])

const headers = {
  "Authorization": "Bearer ms_live_ВАШ_КЛЮЧ",
  "Content-Type": "application/json",
};

const campaign = await (await fetch("https://api.mailsharks.org/v1/campaigns", {
  method: "POST", headers,
  body: JSON.stringify({
    sheet_id: 42,
    template_id: "a7Kd93Xz",
    variant_b: { subject: "Три минуты вашего времени" },
  }),
})).json();

const { ab } = await (await fetch(`https://api.mailsharks.org/v1/campaigns/${campaign.id}`, {
  headers,
})).json();
if (ab.verdict.significant) console.log("Победил вариант", ab.verdict.winner);

curl -G https://api.mailsharks.org/v1/events \
  -H "Authorization: Bearer ms_live_ВАШ_КЛЮЧ" \
  --data-urlencode "since=2026-08-20T09:00:00Z"

# Ответ:
# {"data": [{"at": "2026-08-20T09:04:11Z", "type": "opened",
#             "email": "client@example.com", "campaign_id": 42,
#             "message_id": null}],
#  "next_since": "2026-08-20T09:04:11Z"}

import time, httpx

api = httpx.Client(base_url="https://api.mailsharks.org/v1",
                   headers={"Authorization": "Bearer ms_live_ВАШ_КЛЮЧ"})
since = "2026-08-20T09:00:00Z"

while True:
    page = api.get("/events", params={"since": since}).json()
    for event in page["data"]:
        handle(event)          # ваша обработка
    since = page["next_since"]  # курсор на следующий вызов
    time.sleep(60)              # раз в минуту: чаще нет смысла

let since = "2026-08-20T09:00:00Z";

setInterval(async () => {
  const url = new URL("https://api.mailsharks.org/v1/events");
  url.searchParams.set("since", since);
  const page = await (await fetch(url, {
    headers: { "Authorization": "Bearer ms_live_ВАШ_КЛЮЧ" },
  })).json();
  page.data.forEach(handle);
  since = page.next_since;
}, 60_000);