Campaigns API

Retrieve marketing campaign records and performance metrics.

The Campaigns API provides read access to all email and SMS campaigns in your account. Retrieve campaign lists with key metrics, or get full details on a single campaign including open rates, click rates, and delivery statistics.

Read-Only

The Campaigns API is read-only. Campaigns can be created and managed from the Cashfin dashboard.

Use Cases

• Performance Reporting: Pull open rates, click rates, and send volumes for reporting
• Analytics Integration: Sync campaign metrics to your BI or analytics platform
• Campaign Auditing: Review campaign history and delivery outcomes

Endpoints

Method	Endpoint	Description
GET	/business/campaign/list	List all campaigns
GET	/business/campaign/details/:id	Get campaign details

---

List Campaigns

Retrieve a paginated list of campaigns with performance metrics.

GET /business/campaign/list

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	10	Results per page (max: 100)
search	string	-	Search by title or subject
status	string	-	Filter by status: draft, scheduled, sending, sent, paused, cancelled
medium	string	-	Filter by medium: email, sms
type	string	-	Filter by campaign type

Example Request

cURL

curl -X GET "https://api.cashfin.africa/business/campaign/list?page=1&limit=10&status=sent" \
  -H "Authorization: cs_your_client_secret"

JavaScript

const response = await fetch(
  "https://api.cashfin.africa/business/campaign/list?page=1&limit=10&status=sent",
  {
    headers: { Authorization: "cs_your_client_secret" },
  }
);
const data = await response.json();

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://api.cashfin.africa/business/campaign/list?page=1&limit=10",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => ["Authorization: cs_your_client_secret"],
]);

$result = json_decode(curl_exec($curl), true);

Python

import requests

response = requests.get(
    'https://api.cashfin.africa/business/campaign/list',
    headers={'Authorization': 'cs_your_client_secret'},
    params={'page': 1, 'limit': 10, 'status': 'sent', 'medium': 'email'}
)

Success Response

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439100",
      "title": "January Newsletter",
      "subject": "Your January update from Acme",
      "medium": "email",
      "status": "sent",
      "sentcount": 1250,
      "openscount": 438,
      "clickscount": 87,
      "unsubscribecount": 3,
      "createdat": "2024-01-08T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 34,
    "page": 1,
    "limit": 10,
    "pages": 4
  }
}

---

Get Campaign Details

Retrieve full details and performance metrics for a specific campaign.

GET /business/campaign/details/:id

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Campaign ID (MongoDB ObjectID)

Example Request

cURL

curl -X GET "https://api.cashfin.africa/business/campaign/details/507f1f77bcf86cd799439100" \
  -H "Authorization: cs_your_client_secret"

JavaScript

const campaignId = "507f1f77bcf86cd799439100";

const response = await fetch(
  `https://api.cashfin.africa/business/campaign/details/${campaignId}`,
  {
    headers: { Authorization: "cs_your_client_secret" },
  }
);
const data = await response.json();

Python

import requests

campaign_id = '507f1f77bcf86cd799439100'

response = requests.get(
    f'https://api.cashfin.africa/business/campaign/details/{campaign_id}',
    headers={'Authorization': 'cs_your_client_secret'}
)

Success Response

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439100",
    "title": "January Newsletter",
    "subject": "Your January update from Acme",
    "medium": "email",
    "type": "newsletter",
    "status": "sent",
    "sentcount": 1250,
    "openscount": 438,
    "clickscount": 87,
    "unsubscribecount": 3,
    "bouncecount": 12,
    "scheduledat": "2024-01-08T09:00:00.000Z",
    "createdat": "2024-01-08T10:00:00.000Z",
    "updatedat": "2024-01-08T10:45:00.000Z"
  }
}

---

Campaign Metrics Reference

Field	Type	Description
sentcount	integer	Total number of messages sent
openscount	integer	Number of emails opened
clickscount	integer	Number of link clicks
unsubscribecount	integer	Number of unsubscribes
bouncecount	integer	Number of bounced messages

---

Error Responses

Campaign Not Found

{
  "success": false,
  "error": "Campaign not found"
}

Invalid Campaign ID

{
  "success": false,
  "error": "Invalid campaign ID format"
}