Create a campaign

curl --request POST \
  --url https://apix.spotzee.com/api/client/campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subscription_id": 123,
  "provider_id": 123
}
'

import requests

url = "https://apix.spotzee.com/api/client/campaigns"

payload = {
    "subscription_id": 123,
    "provider_id": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({subscription_id: 123, provider_id: 123})
};

fetch('https://apix.spotzee.com/api/client/campaigns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apix.spotzee.com/api/client/campaigns"

	payload := strings.NewReader("{\n  \"subscription_id\": 123,\n  \"provider_id\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": 24,
  "project_id": 123,
  "type": "blast",
  "name": "<string>",
  "channel": "email",
  "subscription_id": 123,
  "provider_id": 123,
  "state": "draft",
  "created_at": "<string>",
  "updated_at": "<string>",
  "list_ids": [
    123
  ],
  "exclusion_list_ids": [
    123
  ],
  "subscription": {
    "id": 7,
    "project_id": 42,
    "name": "Weekly newsletter",
    "channel": "email",
    "is_public": true,
    "created_at": "<string>",
    "updated_at": "<string>"
  },
  "provider": {
    "id": 19,
    "project_id": 42,
    "type": "smtp",
    "name": "Primary transactional SMTP",
    "group": "email",
    "is_default": true,
    "rate_limit": 0,
    "rate_interval": "second",
    "created_at": "<string>",
    "updated_at": "<string>",
    "deleted_at": "<string>"
  },
  "delivery": {
    "sent": 123,
    "total": 123,
    "opens": 123,
    "clicks": 123,
    "bounced": 123,
    "bounce_categories": {
      "invalid_recipient": 1,
      "mailbox_unavailable": 1,
      "mailbox_full": 1,
      "authentication_failed": 1,
      "policy_blocked": 1,
      "spam_rejected": 1,
      "reputation_blocked": 1,
      "rate_limited": 1,
      "content_rejected": 1,
      "dns_routing_error": 1,
      "transport_error": 1,
      "unknown": 1
    },
    "classification_coverage": {
      "classified": 1,
      "unclassified": 1,
      "total": 1
    },
    "calculated_at": "2023-11-07T05:31:56Z"
  },
  "tags": [
    "<string>"
  ],
  "send_in_user_timezone": true,
  "send_at": "<string>",
  "custom_domain_id": 123,
  "created_by": 123,
  "created_by_admin": {
    "admin_id": 123,
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "jsmith@example.com"
  },
  "description": "<string>"
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

POST

campaigns

Create a campaign

curl --request POST \
  --url https://apix.spotzee.com/api/client/campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subscription_id": 123,
  "provider_id": 123
}
'

import requests

url = "https://apix.spotzee.com/api/client/campaigns"

payload = {
    "subscription_id": 123,
    "provider_id": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({subscription_id: 123, provider_id: 123})
};

fetch('https://apix.spotzee.com/api/client/campaigns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apix.spotzee.com/api/client/campaigns"

	payload := strings.NewReader("{\n  \"subscription_id\": 123,\n  \"provider_id\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": 24,
  "project_id": 123,
  "type": "blast",
  "name": "<string>",
  "channel": "email",
  "subscription_id": 123,
  "provider_id": 123,
  "state": "draft",
  "created_at": "<string>",
  "updated_at": "<string>",
  "list_ids": [
    123
  ],
  "exclusion_list_ids": [
    123
  ],
  "subscription": {
    "id": 7,
    "project_id": 42,
    "name": "Weekly newsletter",
    "channel": "email",
    "is_public": true,
    "created_at": "<string>",
    "updated_at": "<string>"
  },
  "provider": {
    "id": 19,
    "project_id": 42,
    "type": "smtp",
    "name": "Primary transactional SMTP",
    "group": "email",
    "is_default": true,
    "rate_limit": 0,
    "rate_interval": "second",
    "created_at": "<string>",
    "updated_at": "<string>",
    "deleted_at": "<string>"
  },
  "delivery": {
    "sent": 123,
    "total": 123,
    "opens": 123,
    "clicks": 123,
    "bounced": 123,
    "bounce_categories": {
      "invalid_recipient": 1,
      "mailbox_unavailable": 1,
      "mailbox_full": 1,
      "authentication_failed": 1,
      "policy_blocked": 1,
      "spam_rejected": 1,
      "reputation_blocked": 1,
      "rate_limited": 1,
      "content_rejected": 1,
      "dns_routing_error": 1,
      "transport_error": 1,
      "unknown": 1
    },
    "classification_coverage": {
      "classified": 1,
      "unclassified": 1,
      "total": 1
    },
    "calculated_at": "2023-11-07T05:31:56Z"
  },
  "tags": [
    "<string>"
  ],
  "send_in_user_timezone": true,
  "send_at": "<string>",
  "custom_domain_id": 123,
  "created_by": 123,
  "created_by_admin": {
    "admin_id": 123,
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "jsmith@example.com"
  },
  "description": "<string>"
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

{
  "status": "error",
  "code": "resource_missing",
  "message": "User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.",
  "error": "<string>",
  "title": "Resource missing",
  "type": "https://docs.spotzee.com/main-api/errors#resource_missing",
  "request_id": "req_01HXY7Z9K8M5J2N4P6Q8R0S1T2",
  "param": "id",
  "errors": [
    {
      "param": "email",
      "code": "parameter_invalid_format",
      "message": "Must be a valid email address."
    }
  ]
}

Authorizations

Authorization

string

header

required

Project-scoped secret API key (sk_…). Pass in the Authorization: Bearer <key> header. Grants access to the project the key was issued for.

Body

application/json

Create a new campaign. Subscription, provider, and target lists are required to send.

type

enum<string>

required

blast campaigns send to every user in the target lists. trigger campaigns fire per-user when an event matches.

Available options:

blast,

trigger

subscription_id

integer

required

provider_id

integer

required

name

string

Minimum string length: 1

channel

enum<string>

Delivery channel the campaign sends through.

Available options:

email,

text,

push,

webhook,

in_app

list_ids

integer[] | null

exclusion_list_ids

integer[] | null

send_in_user_timezone

boolean | null

send_at

string<date-time> | null

Response

The newly created campaign.

A one-off (blast) or per-user (trigger) send across one channel.

integer

required

Numeric campaign identifier.

Example:

24

project_id

integer

required

type

enum<string>

required

blast campaigns send to every user in the target lists. trigger campaigns fire per-user when an event matches.

Available options:

blast,

trigger

name

string

required

channel

enum<string>

required

Delivery channel the campaign sends through.

Available options:

email,

text,

push,

webhook,

in_app

subscription_id

integer

required

Subscription type a user must be opted in to in order to receive this campaign.

provider_id

integer

required

Delivery provider used to send the campaign.

state

enum<string>

required

Campaign lifecycle state. Set state: "scheduled" (with send_at) to send a blast; set state: "aborted" to cancel.

Available options:

draft,

scheduled,

loading,

running,

finished,

aborting,

aborted

created_at

string | null

required

updated_at

string | null

required

list_ids

integer[] | null

IDs of the lists targeted by the campaign.

exclusion_list_ids

integer[] | null

IDs of lists whose members should be excluded from the campaign.

subscription

object

Hydrated subscription type referenced by subscription_id.

Hide child attributes

subscription.id

integer

required

Numeric subscription-type identifier.

Example:

7

subscription.project_id

integer

required

Identifier of the owning project.

Example:

42

subscription.name

string

required

Human-readable subscription-type name shown on preference centres.

Example:

"Weekly newsletter"

subscription.channel

enum<string>

required

Delivery channel a subscription type covers.

Available options:

email,

text,

push,

webhook,

in_app

Example:

"email"

subscription.is_public

boolean

required

Whether this subscription type is shown on customer-facing preference centres.

subscription.created_at

string | null

required

Time the subscription type was created. ISO 8601.

subscription.updated_at

string | null

required

Time the subscription type was last modified. ISO 8601.

provider

object

Hydrated delivery provider referenced by provider_id. Returned in the redacted public shape — see Provider schema. Credentials (data, auth, API keys, tokens) are NEVER included.

Hide child attributes

provider.id

integer

required

Numeric provider identifier.

Example:

19

provider.project_id

integer

required

Identifier of the owning project.

Example:

42

provider.type

string

required

Provider type within its group — the exact identifier of the underlying integration.

Example:

"smtp"

provider.name

string

required

Human-readable provider name shown in dashboards.

Example:

"Primary transactional SMTP"

provider.group

enum<string>

required

Channel family the provider belongs to.

Available options:

email,

text,

push,

webhook,

analytics

Example:

"email"

provider.is_default

boolean

required

Whether this provider is the default for its group within the project.

provider.rate_limit

integer

required

Maximum sends per rate_interval. Zero means unlimited.

Required range: x >= 0

Example:

0

provider.rate_interval

enum<string>

required

Window over which rate_limit is counted.

Available options:

second,

minute,

hour,

day

Example:

"second"

provider.created_at

string | null

required

Time the provider was created. ISO 8601.

provider.updated_at

string | null

required

Time the provider was last modified. ISO 8601.

provider.deleted_at

string | null

Time the provider was soft-deleted, if applicable.

delivery

object

Aggregated delivery counters for the campaign.

Hide child attributes

delivery.sent

integer

required

delivery.total

integer

required

delivery.opens

integer

required

delivery.clicks

integer

required

delivery.bounced

integer

delivery.bounce_categories

object

Hide child attributes

delivery.bounce_categories.invalid_recipient

integer

Required range: x >= 0

delivery.bounce_categories.mailbox_unavailable

integer

Required range: x >= 0

delivery.bounce_categories.mailbox_full

integer

Required range: x >= 0

delivery.bounce_categories.authentication_failed

integer

Required range: x >= 0

delivery.bounce_categories.policy_blocked

integer

Required range: x >= 0

delivery.bounce_categories.spam_rejected

integer

Required range: x >= 0

delivery.bounce_categories.reputation_blocked

integer

Required range: x >= 0

delivery.bounce_categories.rate_limited

integer

Required range: x >= 0

delivery.bounce_categories.content_rejected

integer

Required range: x >= 0

delivery.bounce_categories.dns_routing_error

integer

Required range: x >= 0

delivery.bounce_categories.transport_error

integer

Required range: x >= 0

delivery.bounce_categories.unknown

integer

Required range: x >= 0

delivery.classification_coverage

object

Hide child attributes

delivery.classification_coverage.classified

integer

required

Required range: x >= 0

delivery.classification_coverage.unclassified

integer

required

Required range: x >= 0

delivery.classification_coverage.total

integer

required

Required range: x >= 0

delivery.calculated_at

string<date-time>

Overview

Projects

Events

Campaigns

Lists

Subscriptions

Journeys

Templates

Users

Tags

API keys

Organisation

Billing recovery

Webhooks

CRM

Source Sync

Form definitions

Form submissions

Create a campaign

Authorizations

Body

Response