API reference

const res = await fetch("https://supermailos.com/api/v1/mailboxes", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/mailboxes",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/threads?folder=inbox&unread=true&limit=25", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/threads",
    params={
        "folder": "inbox",
        "unread": "true",
        "limit": "25",
    },
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/threads/THREAD_ID", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/threads/THREAD_ID",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/threads/THREAD_ID", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "unread": false,
    "folder": "archive",
    "addLabels": [
      "Invoices"
    ]
  }),
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.patch(
    "https://supermailos.com/api/v1/threads/THREAD_ID",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    json={
        "unread": False,
        "folder": "archive",
        "addLabels": ["Invoices"],
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/threads/THREAD_ID/reply", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
    "Content-Type": "application/json",
    // Reuse the same key when retrying this send; never mails twice.
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "text": "Thanks — received, I'll get back to you today.",
    "replyAll": false
  }),
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os, uuid
import requests

res = requests.post(
    "https://supermailos.com/api/v1/threads/THREAD_ID/reply",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it on retries
    },
    json={
        "text": "Thanks — received, I'll get back to you today.",
        "replyAll": False,
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/threads/THREAD_ID/draft", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "text": "Draft for review: thanks, we can do Thursday at 10.",
    "replyAll": true
  }),
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.post(
    "https://supermailos.com/api/v1/threads/THREAD_ID/draft",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    json={
        "text": "Draft for review: thanks, we can do Thursday at 10.",
        "replyAll": True,
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/messages?direction=inbound&limit=20", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/messages",
    params={
        "direction": "inbound",
        "limit": "20",
    },
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/messages/MESSAGE_ID", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/messages/MESSAGE_ID",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

import { writeFile } from "node:fs/promises";

const res = await fetch("https://supermailos.com/api/v1/messages/MESSAGE_ID/raw", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
await writeFile("message.eml", Buffer.from(await res.arrayBuffer()));

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/messages/MESSAGE_ID/raw",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
with open("message.eml", "wb") as f:
    f.write(res.content)

import { writeFile } from "node:fs/promises";

const res = await fetch("https://supermailos.com/api/v1/attachments/ATTACHMENT_ID", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
await writeFile("attachment.bin", Buffer.from(await res.arrayBuffer()));

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/attachments/ATTACHMENT_ID",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
with open("attachment.bin", "wb") as f:
    f.write(res.content)

const res = await fetch("https://supermailos.com/api/v1/search?q=from%3Abilling+has%3Aattachment+after%3A2026-01-01&limit=10", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/search",
    params={
        "q": "from:billing has:attachment after:2026-01-01",
        "limit": "10",
    },
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
    "Content-Type": "application/json",
    // Reuse the same key when retrying this send; never mails twice.
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "from": "you@acme.com",
    "to": "client@example.com",
    "subject": "Your invoice",
    "text": "Hi — your invoice is attached in the portal. Thanks!"
  }),
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os, uuid
import requests

res = requests.post(
    "https://supermailos.com/api/v1/send",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it on retries
    },
    json={
        "from": "you@acme.com",
        "to": "client@example.com",
        "subject": "Your invoice",
        "text": "Hi — your invoice is attached in the portal. Thanks!",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/inboxes", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/inboxes",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/inboxes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Billing assistant",
    "localPart": "billing",
    "sendMode": "known",
    "inboundMode": "verified",
    "createKey": {
      "scopes": [
        "read",
        "write",
        "send"
      ],
      "expiresInDays": 90
    }
  }),
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.post(
    "https://supermailos.com/api/v1/inboxes",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    json={
        "name": "Billing assistant",
        "localPart": "billing",
        "sendMode": "known",
        "inboundMode": "verified",
        "createKey": {
            "scopes": ["read", "write", "send"],
            "expiresInDays": 90,
        },
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/inboxes/INBOX_ID", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/inboxes/INBOX_ID",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/inboxes/INBOX_ID", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "dailySendCap": 50,
    "allowRecipients": [
      "@acme.com"
    ]
  }),
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.patch(
    "https://supermailos.com/api/v1/inboxes/INBOX_ID",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    json={
        "dailySendCap": 50,
        "allowRecipients": ["@acme.com"],
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/inboxes/INBOX_ID", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.delete(
    "https://supermailos.com/api/v1/inboxes/INBOX_ID",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/inboxes/INBOX_ID/keys", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/inboxes/INBOX_ID/keys",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/inboxes/INBOX_ID/keys", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Production worker",
    "scopes": [
      "read",
      "send"
    ],
    "expiresInDays": 30
  }),
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.post(
    "https://supermailos.com/api/v1/inboxes/INBOX_ID/keys",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    json={
        "name": "Production worker",
        "scopes": ["read", "send"],
        "expiresInDays": 30,
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/inboxes/INBOX_ID/keys/KEY_ID", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.delete(
    "https://supermailos.com/api/v1/inboxes/INBOX_ID/keys/KEY_ID",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/holds?inbox=INBOX_ID&status=held", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/holds",
    params={
        "inbox": "INBOX_ID",
        "status": "held",
    },
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/holds/HOLD_ID/release", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.post(
    "https://supermailos.com/api/v1/holds/HOLD_ID/release",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/holds/HOLD_ID/dismiss", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.post(
    "https://supermailos.com/api/v1/holds/HOLD_ID/dismiss",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/approvals?status=pending", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/approvals",
    params={
        "status": "pending",
    },
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/approvals/APPROVAL_ID", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/approvals/APPROVAL_ID",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/approvals/APPROVAL_ID/approve", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "note": "Looks right."
  }),
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.post(
    "https://supermailos.com/api/v1/approvals/APPROVAL_ID/approve",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    json={
        "note": "Looks right.",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/approvals/APPROVAL_ID/reject", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "note": "Don't quote a price; ask them to call."
  }),
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.post(
    "https://supermailos.com/api/v1/approvals/APPROVAL_ID/reject",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    json={
        "note": "Don't quote a price; ask them to call.",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/domains", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/domains",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/domains", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "domain": "acme.com"
  }),
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.post(
    "https://supermailos.com/api/v1/domains",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    json={
        "domain": "acme.com",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/domains/acme.com", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/domains/acme.com",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://supermailos.com/api/v1/domains/acme.com/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const data = await res.json();

import os
import requests

res = requests.post(
    "https://supermailos.com/api/v1/domains/acme.com/verify",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()

import { writeFile } from "node:fs/promises";

const res = await fetch("https://supermailos.com/api/v1/domains/acme.com/zone", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SUPERMAILOS_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
await writeFile("acme.com.zone", Buffer.from(await res.arrayBuffer()));

import os
import requests

res = requests.get(
    "https://supermailos.com/api/v1/domains/acme.com/zone",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMAILOS_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
with open("acme.com.zone", "wb") as f:
    f.write(res.content)