Campaigns

Query campaigns across all channels.

tip

To create campaigns or send messages, use the channel-specific endpoints:

• SMS — POST /sms/campaigns, POST /sms/promotional
• Viber — POST /viber/send

---

List Campaigns

Get a paginated list of campaigns.

GET /api/v1/campaigns

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
pageSize	integer	20	Items per page (max 100)
sendingMode	string	-	Filter: "Bulk" or "Transactional"

Response

{
  "campaigns": [
    {
      "campaignId": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Order Notifications",
      "description": "Real-time order status updates",
      "status": "InProgress",
      "channel": "Smpp",
      "sendingMode": "Transactional",
      "totalMessages": 1543,
      "deliveredCount": 1520,
      "failedCount": 12,
      "pendingCount": 11,
      "seenCount": 1200,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 20,
  "totalPages": 1
}

Campaign Statuses

Status	Description
Draft	Not started
Queuing	Messages are being prepared (bulk send only) — poll until Ready
Ready	All messages inserted, waiting for you to call /start
InProgress	Actively sending
Paused	Temporarily stopped
Completed	All messages processed
Failed	Message preparation failed — re-send to create a new campaign

Example

cURL

# List all campaigns
curl -X GET "https://api.transformify.mk/api/v1/campaigns?page=1&pageSize=20" \
  -H "X-API-Key: your-api-key"

# Filter by sending mode
curl -X GET "https://api.transformify.mk/api/v1/campaigns?sendingMode=Transactional" \
  -H "X-API-Key: your-api-key"

JavaScript

const params = new URLSearchParams({
  page: '1',
  pageSize: '20',
  sendingMode: 'Transactional'
});

const response = await fetch(
  `https://api.transformify.mk/api/v1/campaigns?${params}`,
  {
    headers: { 'X-API-Key': 'your-api-key' }
  }
);

const data = await response.json();

Python

import requests

response = requests.get(
    'https://api.transformify.mk/api/v1/campaigns',
    headers={'X-API-Key': 'your-api-key'},
    params={
        'page': 1,
        'pageSize': 20,
        'sendingMode': 'Transactional'
    }
)

data = response.json()

---

Get Campaign

Get details for a specific campaign.

GET /api/v1/campaigns/{id}

Path Parameters

Parameter	Type	Description
id	UUID	Campaign ID

Response

{
  "campaignId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Order Notifications",
  "description": "Real-time order status updates",
  "status": "InProgress",
  "channel": "Smpp",
  "sendingMode": "Transactional",
  "viberServiceId": null,
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "templateName": "Order Update Template",
  "totalMessages": 1543,
  "deliveredCount": 1520,
  "failedCount": 12,
  "pendingCount": 11,
  "seenCount": 1200,
  "createdAt": "2024-01-15T10:30:00Z",
  "startedAt": "2024-01-15T10:30:00Z"
}

Example

cURL

curl -X GET "https://api.transformify.mk/api/v1/campaigns/660e8400-e29b-41d4-a716-446655440001" \
  -H "X-API-Key: your-api-key"

JavaScript

const campaignId = '660e8400-e29b-41d4-a716-446655440001';

const response = await fetch(
  `https://api.transformify.mk/api/v1/campaigns/${campaignId}`,
  {
    headers: { 'X-API-Key': 'your-api-key' }
  }
);

const campaign = await response.json();
console.log(`Campaign: ${campaign.name}, Status: ${campaign.status}`);

Python

import requests

campaign_id = '660e8400-e29b-41d4-a716-446655440001'

response = requests.get(
    f'https://api.transformify.mk/api/v1/campaigns/{campaign_id}',
    headers={'X-API-Key': 'your-api-key'}
)

campaign = response.json()
print(f"Campaign: {campaign['name']}, Status: {campaign['status']}")

---

Start Campaign

Start a bulk campaign that has reached Ready status, beginning message delivery.

POST /api/v1/campaigns/{id}/start

Path Parameters

Parameter	Type	Description
id	UUID	Campaign ID (from the send response)

Response

{
  "campaignId": "660e8400-e29b-41d4-a716-446655440001",
  "status": "InProgress"
}

note

Only campaigns in Ready status can be started. Campaigns created via POST /api/v1/viber/send or POST /api/v1/sms/promotional must first reach Ready before you call this endpoint.

Example

cURL

curl -X POST "https://api.transformify.mk/api/v1/campaigns/660e8400-e29b-41d4-a716-446655440001/start" \
  -H "X-API-Key: your-api-key"

JavaScript

const campaignId = '660e8400-e29b-41d4-a716-446655440001';

// Poll until Ready, then start
let campaign;
do {
  await new Promise(r => setTimeout(r, 3000));
  const res = await fetch(`https://api.transformify.mk/api/v1/campaigns/${campaignId}`, {
    headers: { 'X-API-Key': 'your-api-key' }
  });
  campaign = await res.json();
} while (campaign.status === 'Queuing');

if (campaign.status === 'Ready') {
  await fetch(`https://api.transformify.mk/api/v1/campaigns/${campaignId}/start`, {
    method: 'POST',
    headers: { 'X-API-Key': 'your-api-key' }
  });
}

Python

import requests, time

campaign_id = '660e8400-e29b-41d4-a716-446655440001'
headers = {'X-API-Key': 'your-api-key'}

# Poll until Ready
while True:
    campaign = requests.get(
        f'https://api.transformify.mk/api/v1/campaigns/{campaign_id}',
        headers=headers
    ).json()
    if campaign['status'] != 'Queuing':
        break
    time.sleep(3)

if campaign['status'] == 'Ready':
    requests.post(
        f'https://api.transformify.mk/api/v1/campaigns/{campaign_id}/start',
        headers=headers
    )

---

Errors

Status	Error	Description
400	Campaign is not ready	Campaign must be in Ready status to start
401	Unauthorized	Invalid API key
404	Not Found	Campaign not found