Monitorsky API Documentation

Complete API reference for managing campaigns, contacts, groups, and monitoring your teams through Microsoft Teams integration.

Base URL: https://api.monitorsky.cloud

Version: 2.0 | Last Updated: August 31, 2025

Quick Navigation

Authentication

All API requests require proper authentication using JWT tokens. The API supports both standard login and Microsoft Teams SSO.

Important: You need a valid MonitorSky JWT token, not a Microsoft Graph token. Use the authentication endpoints to obtain your JWT token. 
Authorization: Bearer YOUR_JWT_TOKEN

Login - Standard Authentication

Authenticate with email/password to receive JWT token.

Endpoint: /monitorsky3-login

Request Body:
{
  "email": "user@example.com",
  "password": "your-password"
}

Teams SSO - Microsoft Teams Authentication

Authenticate using Microsoft Teams SSO token.

Endpoint: /teams-sso-login

Request Body:
{
  "teamsToken": "teams-sso-token",
  "timestamp": "2025-08-31T13:32:53.992Z"
}

API Architecture

The MonitorSky API uses an action-based architecture. All requests are sent to a single endpoint with different action parameters to specify the operation.

POST /webhook/m-api-v2

All API actions use this single endpoint.

Content-Type: application/json

ParameterTypeRequiredDescription
actionstringYesThe API action to perform
timestampstringYesCurrent timestamp in ISO format
...variesNoAdditional parameters specific to each action

Campaigns

Manage your marketing campaigns, create new campaigns, and send messages to your contact groups.

getCampaigns - Get All Campaigns

Retrieve all campaigns for the authenticated user.

Request:
{
  "action": "getCampaigns",
  "timestamp": "2025-08-31T13:32:53.992Z"
}
Response:
{
  "data": [
    {
      "id": "campaign-id",
      "name": "Campaign Name",
      "subject": "Email Subject",
      "status": "Draft",
      "recipients": 100,
      "sent": 85,
      "opened": 42,
      "clicked": 12,
      "openRate": 49.4,
      "clickRate": 14.1,
      "createdAt": "2025-08-30T10:00:00.000Z"
    }
  ]
}

createCampaign - Create New Campaign

Create a new campaign with specified details.

Request:
{
  "action": "createCampaign",
  "campaign": {
    "name": "New Campaign",
    "subject": "Email Subject",
    "message": "Campaign message content",
    "recipients": 100,
    "groups": ["group-id-1", "group-id-2"],
    "schedule": null,
    "template": null
  },
  "timestamp": "2025-08-31T13:32:53.992Z"
}

sendCampaign - Send Campaign

Send an existing campaign to its target recipients.

Request:
{
  "action": "sendCampaign",
  "id": "8960367b-1e03-4824-979f-c6b529189345",
  "timestamp": "2025-08-31T13:32:53.992Z"
}
Response:
{
  "data": [
    {
      "success": true,
      "message": "Campaign sent",
      "sent": 1,
      "opened": 0,
      "clicked": 0,
      "startDate": "2025-08-31T13:32:53.992Z"
    }
  ]
}

updateCampaign - Update Campaign

Update an existing campaign's details.

Request:
{
  "action": "updateCampaign",
  "campaignId": "campaign-id",
  "updates": {
    "name": "Updated Campaign Name",
    "subject": "Updated Subject"
  },
  "timestamp": "2025-08-31T13:32:53.992Z"
}

deleteCampaign - Delete Campaign

Delete a campaign permanently.

Request:
{
  "action": "deleteCampaign",
  "campaignId": "campaign-id",
  "timestamp": "2025-08-31T13:32:53.992Z"
}

Contacts

Manage your contact database, import contacts, and handle contact information.

getContacts - Get All Contacts

Retrieve all contacts for the authenticated user.

Request:
{
  "action": "getContacts",
  "timestamp": "2025-08-31T13:32:53.992Z"
}
Response:
{
  "data": [
    {
      "id": "contact-id",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "company": "Example Corp",
      "jobTitle": "Manager",
      "groups": ["group-id-1"],
      "createdAt": "2025-08-30T10:00:00.000Z"
    }
  ]
}

refreshContacts - Refresh Contacts

Refresh contacts from connected Microsoft Graph/Teams.

Request:
{
  "action": "refreshContacts",
  "timestamp": "2025-08-31T13:32:53.992Z"
}

createContact - Create New Contact

Add a new contact to your database.

Request:
{
  "action": "createContact",
  "contact": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+1987654321",
    "company": "New Corp",
    "jobTitle": "Director"
  },
  "timestamp": "2025-08-31T13:32:53.992Z"
}

updateContact - Update Contact

Update an existing contact's information.

Request:
{
  "action": "updateContact",
  "contactId": "contact-id",
  "updates": {
    "name": "Updated Name",
    "jobTitle": "Senior Manager"
  },
  "timestamp": "2025-08-31T13:32:53.992Z"
}

deleteContact - Delete Contact

Remove a contact from your database.

Request:
{
  "action": "deleteContact",
  "contactId": "contact-id",
  "timestamp": "2025-08-31T13:32:53.992Z"
}

Groups

Organize your contacts into groups for targeted campaign delivery.

getGroups - Get All Groups

Retrieve all contact groups.

Request:
{
  "action": "getGroups",
  "timestamp": "2025-08-31T13:32:53.992Z"
}
Response:
{
  "data": [
    {
      "id": "group-id",
      "name": "Marketing Team",
      "description": "Marketing department contacts",
      "color": "blue",
      "member_count": 25,
      "is_active": true,
      "created_at": "2025-08-30T10:00:00.000Z"
    }
  ]
}

getGroupMembers - Get Group Members

Get all contacts in a specific group.

Request:
{
  "action": "getGroupMembers",
  "groupId": "group-id",
  "timestamp": "2025-08-31T13:32:53.992Z"
}

createGroup - Create New Group

Create a new contact group.

Request:
{
  "action": "createGroup",
  "group": {
    "name": "Sales Team",
    "description": "Sales department contacts",
    "color": "green"
  },
  "timestamp": "2025-08-31T13:32:53.992Z"
}

addContactToGroup - Add Contact to Group

Add a contact to a specific group.

Request:
{
  "action": "addContactToGroup",
  "contactId": "contact-id",
  "groupID": "group-id",
  "timestamp": "2025-08-31T13:32:53.992Z"
}

removeContactFromGroup - Remove Contact from Group

Remove a contact from a specific group.

Request:
{
  "action": "removeContactFromGroup",
  "contactId": "contact-id",
  "groupID": "group-id",
  "timestamp": "2025-08-31T13:32:53.992Z"
}

addAllContactsToGroup - Add All Contacts to Group

Add all existing contacts to a specific group.

Request:
{
  "action": "addAllContactsToGroup",
  "groupId": "group-id",
  "timestamp": "2025-08-31T13:32:53.992Z"
}

Dashboard & Analytics

Get comprehensive statistics and analytics about your campaigns, contacts, and system performance.

getDashboardStats - Get Dashboard Statistics

Retrieve comprehensive dashboard statistics.

Request:
{
  "action": "getDashboardStats",
  "startDate": "2025-08-01T00:00:00.000Z",
  "endDate": "2025-08-31T23:59:59.999Z",
  "period": "month",
  "includeBreakdowns": true,
  "timestamp": "2025-08-31T13:32:53.992Z"
}
Response:
{
  "data": [
    {
      "totalMessagesSent": 1250,
      "totalMessagesDelivered": 1198,
      "totalMessagesOpened": 589,
      "totalMessagesClicked": 156,
      "overallDeliveryRate": 95.8,
      "overallOpenRate": 49.2,
      "overallClickRate": 13.0,
      "totalCampaigns": 12,
      "activeCampaigns": 3,
      "totalContacts": 450,
      "totalGroups": 8
    }
  ]
}

getCampaignPerformance - Get Campaign Performance

Get detailed performance metrics for campaigns.

Request:
{
  "action": "getCampaignPerformance",
  "startDate": "2025-08-01T00:00:00.000Z",
  "endDate": "2025-08-31T23:59:59.999Z",
  "campaignIds": ["campaign-id-1", "campaign-id-2"],
  "timestamp": "2025-08-31T13:32:53.992Z"
}

getContactAnalytics - Get Contact Analytics

Get contact growth and engagement analytics.

Request:
{
  "action": "getContactAnalytics",
  "startDate": "2025-08-01T00:00:00.000Z",
  "endDate": "2025-08-31T23:59:59.999Z",
  "includeGroups": true,
  "timestamp": "2025-08-31T13:32:53.992Z"
}

getSystemStatus - Get System Status

Check system health and status.

Request:
{
  "action": "getSystemStatus",
  "timestamp": "2025-08-31T13:32:53.992Z"
}

Unsubscribe System

Handle unsubscribe requests and manage opt-out preferences.

validateUnsubscribeToken - Validate Unsubscribe Token

Validate a JWT token from an unsubscribe link.

Request:
{
  "action": "validateUnsubscribeToken",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
  "timestamp": "2025-08-31T13:32:53.992Z"
}

processUnsubscribe - Process Unsubscribe

Process an unsubscribe request.

Request:
{
  "action": "processUnsubscribe",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
  "unsubscribeType": "all",
  "contactId": "contact-id",
  "timestamp": "2025-08-31T13:32:53.992Z"
}

generateUnsubscribeToken - Generate Unsubscribe Token

Generate an unsubscribe token for a contact.

Request:
{
  "action": "generateUnsubscribeToken",
  "contactId": "contact-id",
  "email": "contact@example.com",
  "timestamp": "2025-08-31T13:32:53.992Z"
}

Microsoft Graph OAuth

Manage Microsoft Graph integration for Teams and Office 365 connectivity.

connectMSGraph - Connect Microsoft Graph

Initiate Microsoft Graph OAuth connection.

Request:
{
  "action": "connectMSGraph",
  "microsoftUsername": "user@company.com",
  "email": "user@company.com",
  "timestamp": "2025-08-31T13:32:53.992Z"
}

checkMSGraphStatus - Check Microsoft Graph Status

Check the status of Microsoft Graph connection.

Request:
{
  "action": "checkMSGraphStatus",
  "microsoftUsername": "user@company.com",
  "timestamp": "2025-08-31T13:32:53.992Z"
}

checkGraphIsConnected - Check Graph Connection

Check if Microsoft Graph is currently connected.

Request:
{
  "action": "checkGraphIsConnected",
  "timestamp": "2025-08-31T13:32:53.992Z"
}
Response:
{
  "data": [
    {
      "connected": true,
      "ping": 42,
      "region": "weu"
    }
  ]
}

Code Examples

cURL Examples

# Send a campaign
curl -X POST https://api.monitorsky.cloud/webhook/m-api-v2 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "action": "sendCampaign",
    "id": "your-campaign-id",
    "timestamp": "'$(date -Iseconds)'"
  }'

# Get all campaigns
curl -X POST https://api.monitorsky.cloud/webhook/m-api-v2 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "action": "getCampaigns",
    "timestamp": "'$(date -Iseconds)'"
  }'

# Get dashboard statistics
curl -X POST https://api.monitorsky.cloud/webhook/m-api-v2 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "action": "getDashboardStats",
    "period": "month",
    "timestamp": "'$(date -Iseconds)'"
  }'

JavaScript/Node.js Example

const monitorSkyAPI = async (action, payload = {}) => {
  const response = await fetch('https://api.monitorsky.cloud/webhook/m-api-v2', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${YOUR_JWT_TOKEN}`
    },
    body: JSON.stringify({
      action,
      timestamp: new Date().toISOString(),
      ...payload
    })
  });
  
  return await response.json();
};

// Usage examples
const campaigns = await monitorSkyAPI('getCampaigns');
console.log(campaigns.data);

const campaignResult = await monitorSkyAPI('sendCampaign', {
  id: 'campaign-id-here'
});
console.log(campaignResult.data);

const stats = await monitorSkyAPI('getDashboardStats', {
  period: 'month',
  includeBreakdowns: true
});

Python Example

import requests
import json
from datetime import datetime

def monitorsky_api(action, payload=None):
    if payload is None:
        payload = {}
    
    data = {
        'action': action,
        'timestamp': datetime.now().isoformat() + 'Z',
        **payload
    }
    
    response = requests.post(
        'https://api.monitorsky.cloud/webhook/m-api-v2',
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {YOUR_JWT_TOKEN}'
        },
        json=data
    )
    
    return response.json()

# Usage
campaigns = monitorsky_api('getCampaigns')
print(campaigns['data'])

send_result = monitorsky_api('sendCampaign', {'id': 'campaign-id'})
print(send_result['data'])

Response Format

All successful responses follow this format:

{
  "data": [
    {
      // Response data object(s)
    }
  ]
}

Error Handling

HTTP StatusDescriptionCommon Causes
200SuccessRequest processed successfully
400Bad RequestInvalid request format, missing required parameters
401UnauthorizedInvalid or missing JWT token
404Not FoundResource not found, invalid endpoint
500Internal Server ErrorServer-side error in n8n workflow

Rate Limits & Best Practices