Helstify — Email marketing

Overview

GET/businesses/{business}/marketing/overview

Sending state, plan, usage today and this month, and verified senders.

Needs the marketing:read scope.

Parameters

business integer, in path, required: The business id, from GET /businesses.

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

const res = await fetch("https://helstify.com/api/v1/businesses/60/marketing/overview", {
  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/marketing/overview",
    headers={"Authorization": f"Bearer {os.environ['HELSTIFY_KEY']}"},
)
print(res.json())

Response200

{
    "sending_enabled": true,
    "usage": {
        "contacts": 1240,
        "sent_this_month": 3800,
        "sent_today": 0,
        "warmup_ceiling_today": 800
    },
    "counts": {
        "lists": 3,
        "campaigns": 7
    }
}

Add a contact

POST/businesses/{business}/marketing/contacts

Adds one contact. consent and consent_source are required: say where they agreed to hear from you.

Needs the marketing:write scope.

Parameters

business integer, in path, required: The business id, from GET /businesses.

Body

email string: For example sam@example.com
first_name string: For example Sam
lists array: For example [4]
fields object: For example {"city":"Pune"}
consent boolean: For example true
consent_source string: For example Checkout opt-in, 9 Nov 2026

curl -X POST "https://helstify.com/api/v1/businesses/60/marketing/contacts" \
  -H "Authorization: Bearer $HELSTIFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"sam@example.com","first_name":"Sam","lists":[4],"fields":{"city":"Pune"},"consent":true,"consent_source":"Checkout opt-in, 9 Nov 2026"}'

const res = await fetch("https://helstify.com/api/v1/businesses/60/marketing/contacts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HELSTIFY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "email": "sam@example.com",
      "first_name": "Sam",
      "lists": [
          4
      ],
      "fields": {
          "city": "Pune"
      },
      "consent": true,
      "consent_source": "Checkout opt-in, 9 Nov 2026"
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://helstify.com/api/v1/businesses/60/marketing/contacts",
    headers={"Authorization": f"Bearer {os.environ['HELSTIFY_KEY']}"},
    json={
        "email": "sam@example.com",
        "first_name": "Sam",
        "lists": [
            4
        ],
        "fields": {
            "city": "Pune"
        },
        "consent": True,
        "consent_source": "Checkout opt-in, 9 Nov 2026"
    },
)
print(res.json())

Response201

{
    "id": 2210,
    "email": "sam@example.com",
    "first_name": "Sam",
    "last_name": null,
    "status": "subscribed",
    "source": "api",
    "fields": {
        "city": "Pune"
    }
}

List campaigns

GET/businesses/{business}/marketing/campaigns

Every campaign, with its state and stats.

Needs the marketing:read scope.

Parameters

business integer, in path, required: The business id, from GET /businesses.

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

const res = await fetch("https://helstify.com/api/v1/businesses/60/marketing/campaigns", {
  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/marketing/campaigns",
    headers={"Authorization": f"Bearer {os.environ['HELSTIFY_KEY']}"},
)
print(res.json())

Response200

[
    {
        "id": 9,
        "name": "November roast",
        "subject": "The November roast",
        "status": "sent",
        "recipients": 1204,
        "sent": 1180,
        "delivered": 1171,
        "opens": 512,
        "clicks": 96,
        "bounces": 9,
        "unsubscribes": 4
    }
]

Create a campaign

POST/businesses/{business}/marketing/campaigns

A draft. Check it, test it, then send it.

Needs the marketing:write scope.

Parameters

business integer, in path, required: The business id, from GET /businesses.

Body

name string: For example December roast
subject string: For example Winter blend is here
lists array: For example [4]
html string: For example <h1>Winter blend</h1>…

curl -X POST "https://helstify.com/api/v1/businesses/60/marketing/campaigns" \
  -H "Authorization: Bearer $HELSTIFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"December roast","subject":"Winter blend is here","lists":[4],"html":"<h1>Winter blend</h1>…"}'

const res = await fetch("https://helstify.com/api/v1/businesses/60/marketing/campaigns", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HELSTIFY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "name": "December roast",
      "subject": "Winter blend is here",
      "lists": [
          4
      ],
      "html": "<h1>Winter blend</h1>…"
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://helstify.com/api/v1/businesses/60/marketing/campaigns",
    headers={"Authorization": f"Bearer {os.environ['HELSTIFY_KEY']}"},
    json={
        "name": "December roast",
        "subject": "Winter blend is here",
        "lists": [
            4
        ],
        "html": "<h1>Winter blend</h1>…"
    },
)
print(res.json())

Response201

{
    "id": 10,
    "name": "December roast",
    "subject": "Winter blend is here",
    "status": "draft",
    "audience": {
        "lists": [
            4
        ],
        "segments": [],
        "exclude_lists": []
    },
    "next": "POST campaigns/10/check, then /test, then /send"
}

Send a campaign

POST/businesses/{business}/marketing/campaigns/{id}/send

Queues it. Paced by the plan and the domain's warm-up.

Needs the marketing:write scope.

Parameters

business integer, in path, required: The business id, from GET /businesses.
id integer, in path, required: The campaign id.

curl -X POST "https://helstify.com/api/v1/businesses/60/marketing/campaigns/14/send" \
  -H "Authorization: Bearer $HELSTIFY_KEY"

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

import os, requests

res = requests.post(
    "https://helstify.com/api/v1/businesses/60/marketing/campaigns/14/send",
    headers={"Authorization": f"Bearer {os.environ['HELSTIFY_KEY']}"},
)
print(res.json())

Response200

{
    "id": 10,
    "name": "December roast",
    "status": "sending",
    "message": "Sending now."
}

Send one transactional email

POST/businesses/{business}/marketing/send

A single message to one person, tracked like a campaign.

Needs the marketing:write scope.

Parameters

business integer, in path, required: The business id, from GET /businesses.

Body

from string: For example orders@northwind.coffee
to string: For example sam@example.com
subject string: For example Your order shipped
html string: For example <p>On its way.</p>
type string: For example transactional

curl -X POST "https://helstify.com/api/v1/businesses/60/marketing/send" \
  -H "Authorization: Bearer $HELSTIFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"orders@northwind.coffee","to":"sam@example.com","subject":"Your order shipped","html":"<p>On its way.</p>","type":"transactional"}'

const res = await fetch("https://helstify.com/api/v1/businesses/60/marketing/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HELSTIFY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "from": "orders@northwind.coffee",
      "to": "sam@example.com",
      "subject": "Your order shipped",
      "html": "<p>On its way.</p>",
      "type": "transactional"
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://helstify.com/api/v1/businesses/60/marketing/send",
    headers={"Authorization": f"Bearer {os.environ['HELSTIFY_KEY']}"},
    json={
        "from": "orders@northwind.coffee",
        "to": "sam@example.com",
        "subject": "Your order shipped",
        "html": "<p>On its way.</p>",
        "type": "transactional"
    },
)
print(res.json())

Response202

{
    "message_id": "k3j9x0q2m8w1v7c4b6n5z0a1",
    "status": "queued"
}