Mail

List mail domains

GET/businesses/{business}/mail/domains

Domains with mail turned on.

Needs the mail:read scope.

Parameters

business integer, in path, required

The business id, from GET /businesses.

curl "https://helstify.com/api/v1/businesses/60/mail/domains" \
  -H "Authorization: Bearer $HELSTIFY_KEY"

const res = await fetch("https://helstify.com/api/v1/businesses/60/mail/domains", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.HELSTIFY_KEY}`,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://helstify.com/api/v1/businesses/60/mail/domains",
    headers={"Authorization": f"Bearer {os.environ['HELSTIFY_KEY']}"},
)
print(res.json())

{
    "domains": [
        {
            "domain": "northwind.coffee",
            "mailboxes": 2
        }
    ]
}

List mailboxes

GET/businesses/{business}/mail/mailboxes

Every mailbox on one domain.

Needs the mail:read scope.

Parameters

business integer, in path, required

The business id, from GET /businesses.

domain string, in query

Defaults to the primary domain.

curl "https://helstify.com/api/v1/businesses/60/mail/mailboxes" \
  -H "Authorization: Bearer $HELSTIFY_KEY"

const res = await fetch("https://helstify.com/api/v1/businesses/60/mail/mailboxes", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.HELSTIFY_KEY}`,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://helstify.com/api/v1/businesses/60/mail/mailboxes",
    headers={"Authorization": f"Bearer {os.environ['HELSTIFY_KEY']}"},
)
print(res.json())

{
    "domain": "northwind.coffee",
    "mailboxes": [
        {
            "id": 31,
            "email": "hello@northwind.coffee",
            "quota_mb": 2048,
            "active": true,
            "by_agent": false,
            "has_password": true
        }
    ]
}

Create a mailbox

POST/businesses/{business}/mail/mailboxes

Returns the new password once. Store it.

Needs the mail:write scope.

Parameters

business integer, in path, required

The business id, from GET /businesses.

Body

local_part string

For example orders

quota_mb integer

For example 1024

curl -X POST "https://helstify.com/api/v1/businesses/60/mail/mailboxes" \
  -H "Authorization: Bearer $HELSTIFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"local_part":"orders","quota_mb":1024}'

const res = await fetch("https://helstify.com/api/v1/businesses/60/mail/mailboxes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HELSTIFY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "local_part": "orders",
      "quota_mb": 1024
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://helstify.com/api/v1/businesses/60/mail/mailboxes",
    headers={"Authorization": f"Bearer {os.environ['HELSTIFY_KEY']}"},
    json={
        "local_part": "orders",
        "quota_mb": 1024
    },
)
print(res.json())

{
    "mailbox": {
        "id": 32,
        "email": "orders@northwind.coffee",
        "quota_mb": 1024,
        "active": true,
        "by_agent": true,
        "has_password": true
    },
    "password": "q7M-…"
}

Update a mailbox

PATCH/businesses/{business}/mail/mailboxes/{mailbox}

Change quota, pause it, or rotate its password.

Needs the mail:write scope.

Parameters

business integer, in path, required

The business id, from GET /businesses.

mailbox integer, in path, required

The mailbox id, from GET …/mail/mailboxes.

Body

quota_mb integer

For example 4096

rotate_password boolean

For example false

curl -X PATCH "https://helstify.com/api/v1/businesses/60/mail/mailboxes/31" \
  -H "Authorization: Bearer $HELSTIFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quota_mb":4096,"rotate_password":false}'

const res = await fetch("https://helstify.com/api/v1/businesses/60/mail/mailboxes/31", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.HELSTIFY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "quota_mb": 4096,
      "rotate_password": false
  }),
});
const data = await res.json();

import os, requests

res = requests.patch(
    "https://helstify.com/api/v1/businesses/60/mail/mailboxes/31",
    headers={"Authorization": f"Bearer {os.environ['HELSTIFY_KEY']}"},
    json={
        "quota_mb": 4096,
        "rotate_password": False
    },
)
print(res.json())

{
    "mailbox": {
        "id": 32,
        "email": "orders@northwind.coffee",
        "quota_mb": 4096,
        "active": true
    }
}

Delete a mailbox

DELETE/businesses/{business}/mail/mailboxes/{mailbox}

Deletes the mailbox and every message in it.

Needs the mail:write scope.

Parameters

business integer, in path, required

The business id, from GET /businesses.

mailbox integer, in path, required

The mailbox id, from GET …/mail/mailboxes.

curl -X DELETE "https://helstify.com/api/v1/businesses/60/mail/mailboxes/31" \
  -H "Authorization: Bearer $HELSTIFY_KEY"

const res = await fetch("https://helstify.com/api/v1/businesses/60/mail/mailboxes/31", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.HELSTIFY_KEY}`,
  },
});
const data = await res.json();

import os, requests

res = requests.delete(
    "https://helstify.com/api/v1/businesses/60/mail/mailboxes/31",
    headers={"Authorization": f"Bearer {os.environ['HELSTIFY_KEY']}"},
)
print(res.json())

{
    "deleted": true
}

Import existing mailboxes

POST/businesses/{business}/mail/mailboxes/import

Adopt mailboxes that already exist on the mail server for this domain.

Needs the mail:write scope.

Parameters

business integer, in path, required

The business id, from GET /businesses.

Body

domain string

For example northwind.coffee

curl -X POST "https://helstify.com/api/v1/businesses/60/mail/mailboxes/import" \
  -H "Authorization: Bearer $HELSTIFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"northwind.coffee"}'

const res = await fetch("https://helstify.com/api/v1/businesses/60/mail/mailboxes/import", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HELSTIFY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "domain": "northwind.coffee"
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://helstify.com/api/v1/businesses/60/mail/mailboxes/import",
    headers={"Authorization": f"Bearer {os.environ['HELSTIFY_KEY']}"},
    json={
        "domain": "northwind.coffee"
    },
)
print(res.json())

{
    "imported": 1,
    "mailboxes": []
}

List messages

GET/businesses/{business}/mail/mailboxes/{mailbox}/messages

Newest first.

Needs the mail:read scope.

Parameters

business integer, in path, required

The business id, from GET /businesses.

mailbox integer, in path, required

The mailbox id, from GET …/mail/mailboxes.

folder string, in query

INBOX by default.

page integer, in query

Page number.

curl "https://helstify.com/api/v1/businesses/60/mail/mailboxes/31/messages" \
  -H "Authorization: Bearer $HELSTIFY_KEY"

const res = await fetch("https://helstify.com/api/v1/businesses/60/mail/mailboxes/31/messages", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.HELSTIFY_KEY}`,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://helstify.com/api/v1/businesses/60/mail/mailboxes/31/messages",
    headers={"Authorization": f"Bearer {os.environ['HELSTIFY_KEY']}"},
)
print(res.json())

{
    "folder": "INBOX",
    "total": 1,
    "messages": [
        {
            "uid": 118,
            "from": "Sam <sam@example.com>",
            "subject": "Wholesale order",
            "date": "2026-11-08T14:01:00Z",
            "unread": true,
            "has_attachments": false,
            "preview": "Hi, could we get 20kg of…"
        }
    ]
}

Read a message

GET/businesses/{business}/mail/mailboxes/{mailbox}/messages/{uid}

The full message as text.

Needs the mail:read scope.

Parameters

business integer, in path, required

The business id, from GET /businesses.

mailbox integer, in path, required

The mailbox id, from GET …/mail/mailboxes.

uid integer, in path, required

The message uid.

curl "https://helstify.com/api/v1/businesses/60/mail/mailboxes/31/messages/118" \
  -H "Authorization: Bearer $HELSTIFY_KEY"

const res = await fetch("https://helstify.com/api/v1/businesses/60/mail/mailboxes/31/messages/118", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.HELSTIFY_KEY}`,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://helstify.com/api/v1/businesses/60/mail/mailboxes/31/messages/118",
    headers={"Authorization": f"Bearer {os.environ['HELSTIFY_KEY']}"},
)
print(res.json())

{
    "message": {
        "uid": 118,
        "from": "Sam <sam@example.com>",
        "to": "orders@northwind.coffee",
        "cc": "",
        "subject": "Wholesale order",
        "date": "2026-11-08T14:01:00Z",
        "body": "Hi, could we get 20kg of the house blend…",
        "attachments": []
    }
}

Send an email

POST/businesses/{business}/mail/mailboxes/{mailbox}/send

Sent from that mailbox, with a copy in its Sent folder.

Needs the mail:send scope.

Parameters

business integer, in path, required

The business id, from GET /businesses.

mailbox integer, in path, required

The mailbox id, from GET …/mail/mailboxes.

Body

to string

For example sam@example.com

subject string

For example Re: Wholesale order

body string

For example Yes, we can ship on Thursday.

curl -X POST "https://helstify.com/api/v1/businesses/60/mail/mailboxes/31/send" \
  -H "Authorization: Bearer $HELSTIFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"sam@example.com","subject":"Re: Wholesale order","body":"Yes, we can ship on Thursday."}'

const res = await fetch("https://helstify.com/api/v1/businesses/60/mail/mailboxes/31/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HELSTIFY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "to": "sam@example.com",
      "subject": "Re: Wholesale order",
      "body": "Yes, we can ship on Thursday."
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://helstify.com/api/v1/businesses/60/mail/mailboxes/31/send",
    headers={"Authorization": f"Bearer {os.environ['HELSTIFY_KEY']}"},
    json={
        "to": "sam@example.com",
        "subject": "Re: Wholesale order",
        "body": "Yes, we can ship on Thursday."
    },
)
print(res.json())

{
    "sent": true
}