API Reference

Complete API documentation for FlowCampaign's REST API. Use this reference to integrate email campaign functionality into your applications.

Base URL

Development: http://localhost:8787
Production: https://mails.nssoftwaresolutions.in

Authentication

All API endpoints require authentication using Bearer tokens.

Getting API Keys

Log into FlowCampaign dashboard
Navigate to Settings > API Keys
Click "Generate New API Key"
Copy the generated key (displayed only once)

Authentication Header

Authorization: Bearer YOUR_API_KEY

Rate Limiting

Standard Plan: 100 requests per minute per API key
Pro Plan: 1000 requests per minute per API key
Enterprise Plan: Custom limits

Response Format

All API responses follow this format:

{
  "success": true,
  "data": {},
  "message": "Operation completed successfully",
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Responses

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address",
    "details": {
      "email": "Must be a valid email address"
    }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Common Error Codes

Code	Description	HTTP Status
`AUTH_REQUIRED`	Authentication required	401
`INVALID_TOKEN`	Invalid or expired token	401
`PERMISSION_DENIED`	Insufficient permissions	403
`NOT_FOUND`	Resource not found	404
`VALIDATION_ERROR`	Request validation failed	422
`RATE_LIMITED`	Rate limit exceeded	429
`SERVER_ERROR`	Internal server error	500

Endpoints

Authentication

Get API Status

GET /health

Response:

{
  "success": true,
  "data": {
    "status": "healthy",
    "version": "1.0.0",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Campaigns

List Campaigns

GET /campaigns

Query Parameters:

page (optional): Page number (default: 1)
limit (optional): Items per page (default: 20, max: 100)
status (optional): Filter by status (draft, scheduled, sent, cancelled)
search (optional): Search by campaign name

Response:

{
  "success": true,
  "data": {
    "campaigns": [
      {
        "id": "camp_123456",
        "name": "Welcome Campaign",
        "status": "sent",
        "subject": "Welcome to Our Platform!",
        "sent_at": "2024-01-15T10:00:00Z",
        "stats": {
          "sent": 1000,
          "delivered": 980,
          "opened": 250,
          "clicked": 120,
          "bounced": 20,
          "unsubscribed": 5
        },
        "created_at": "2024-01-14T15:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "pages": 3
    }
  }
}

Get Campaign Details

GET /campaigns/{id}

Response:

{
  "success": true,
  "data": {
    "id": "camp_123456",
    "name": "Welcome Campaign",
    "subject": "Welcome to Our Platform!",
    "preview_text": "Get started with our platform...",
    "content": "<html>...</html>",
    "status": "sent",
    "schedule": {
      "type": "immediate",
      "date": "2024-01-15T10:00:00Z"
    },
    "audience": {
      "type": "list",
      "list_id": "list_789",
      "segment_id": null
    },
    "tracking": {
      "track_opens": true,
      "track_clicks": true,
      "utm_params": {
        "source": "flowcampaign",
        "medium": "email"
      }
    },
    "stats": {
      "sent": 1000,
      "delivered": 980,
      "opened": 250,
      "clicked": 120,
      "bounced": 20,
      "unsubscribed": 5,
      "open_rate": 25.5,
      "click_rate": 12.2,
      "bounce_rate": 2.0
    },
    "created_at": "2024-01-14T15:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Create Campaign

POST /campaigns

Request Body:

{
  "name": "New Campaign",
  "subject": "Welcome to Our Service",
  "preview_text": "Get started with our amazing service...",
  "content": "<html><body><h1>Welcome!</h1></body></html>",
  "template_id": "template_123",
  "audience": {
    "type": "list",
    "list_id": "list_789"
  },
  "schedule": {
    "type": "scheduled",
    "date": "2024-01-20T10:00:00Z"
  },
  "tracking": {
    "track_opens": true,
    "track_clicks": true,
    "utm_params": {
      "source": "newsletter",
      "medium": "email",
      "campaign": "welcome"
    }
  },
  "settings": {
    "from_email": "noreply@yourdomain.com",
    "from_name": "Your Company",
    "reply_to": "support@yourdomain.com"
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "camp_new123",
    "name": "New Campaign",
    "status": "draft",
    "created_at": "2024-01-15T11:00:00Z"
  }
}

Update Campaign

PUT /campaigns/{id}

Request Body: Same as create, partial updates allowed

Send Campaign

POST /campaigns/{id}/send

Request Body:

{
  "send_test": false,
  "test_emails": ["test@example.com"],
  "confirm": true
}

Response:

{
  "success": true,
  "data": {
    "campaign_id": "camp_123456",
    "status": "scheduled",
    "scheduled_for": "2024-01-15T12:00:00Z",
    "estimated_recipients": 1000
  }
}

Cancel Campaign

POST /campaigns/{id}/cancel

Get Campaign Analytics

GET /campaigns/{id}/analytics

Query Parameters:

timeframe (optional): last_7_days, last_30_days, custom
start_date (optional): Start date for custom timeframe
end_date (optional): End date for custom timeframe

Contacts

List Contacts

GET /contacts

Query Parameters:

page, limit: Pagination
list_id (optional): Filter by list
tag (optional): Filter by tag
status (optional): active, unsubscribed, bounced
search (optional): Search by email or name

Get Contact

GET /contacts/{id}

Create Contact

POST /contacts

Request Body:

{
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+1234567890",
  "tags": ["customer", "premium"],
  "custom_fields": {
    "company": "Example Corp",
    "job_title": "Developer"
  },
  "lists": ["list_123", "list_456"]
}

Update Contact

PUT /contacts/{id}

Delete Contact

DELETE /contacts/{id}

GDPR Note: Use DELETE endpoint for GDPR right to erasure compliance.

Import Contacts (Bulk)

POST /contacts/import

Request Body (multipart/form-data):

file: CSV file with contacts
list_id (optional): Add to specific list
tags (optional): Comma-separated tags to apply
update_existing (optional): Update existing contacts (true/false)

CSV Format:

email,first_name,last_name,tags,custom_field1,custom_field2
john@example.com,John,Doe,customer;premium,Example Corp,Developer
jane@example.com,Jane,Smith,lead,,Designer

Export Contacts

GET /contacts/export

Query Parameters:

format (optional): csv, json (default: csv)
list_id (optional): Export specific list
fields (optional): Comma-separated fields to include

Lists

List Contact Lists

GET /lists

Create List

POST /lists

Request Body:

{
  "name": "Newsletter Subscribers",
  "description": "Users who subscribed to newsletter",
  "visibility": "private",
  "double_opt_in": true
}

Update List

PUT /lists/{id}

Delete List

DELETE /lists/{id}

Note: Deleting a list doesn't delete contacts, only removes the list association.

Templates

List Templates

GET /templates

Get Template

GET /templates/{id}

Create Template

POST /templates

Request Body:

{
  "name": "Welcome Email",
  "subject": "Welcome to {{company_name}}",
  "content": "<html>...{{first_name}}...</html>",
  "type": "html",
  "category": "onboarding",
  "variables": ["first_name", "company_name"],
  "preview_url": "https://example.com/preview"
}

Update Template

PUT /templates/{id}

Delete Template

DELETE /templates/{id}

Preview Template

POST /templates/{id}/preview

Request Body:

{
  "variables": {
    "first_name": "John",
    "company_name": "Example Corp"
  }
}

Email Sending

Send Single Email

POST /email/send

Request Body:

{
  "to": "recipient@example.com",
  "cc": ["cc1@example.com", "cc2@example.com"],
  "bcc": ["bcc@example.com"],
  "subject": "Test Email",
  "html": "<h1>Hello {{name}}</h1><p>This is a test email.</p>",
  "text": "Hello {{name}}\nThis is a test email.",
  "template_id": "template_123",
  "variables": {
    "name": "John Doe",
    "company": "Example Corp"
  },
  "attachments": [
    {
      "filename": "document.pdf",
      "content": "base64_encoded_content",
      "type": "application/pdf"
    }
  ],
  "tracking": {
    "track_opens": true,
    "track_clicks": true
  },
  "metadata": {
    "campaign_id": "camp_123",
    "user_id": "user_456"
  }
}

Send Bulk Emails

POST /email/bulk

Request Body:

{
  "recipients": [
    {
      "to": "user1@example.com",
      "variables": {
        "name": "User One"
      }
    },
    {
      "to": "user2@example.com",
      "variables": {
        "name": "User Two"
      }
    }
  ],
  "subject": "Bulk Email Test",
  "html": "<h1>Hello {{name}}</h1>",
  "template_id": "template_123",
  "send_in_parallel": true,
  "batch_size": 100
}

Analytics

Get Overall Analytics

GET /analytics/overall

Query Parameters:

start_date (required): Start date (YYYY-MM-DD)
end_date (required): End date (YYYY-MM-DD)
group_by (optional): day, week, month

Response:

{
  "success": true,
  "data": {
    "period": {
      "start": "2024-01-01",
      "end": "2024-01-31"
    },
    "summary": {
      "campaigns_sent": 15,
      "total_emails_sent": 12500,
      "total_delivered": 12250,
      "total_opened": 3675,
      "total_clicked": 1470,
      "total_bounced": 250,
      "total_unsubscribed": 63,
      "delivery_rate": 98.0,
      "open_rate": 30.0,
      "click_rate": 12.0
    },
    "trends": [
      {
        "date": "2024-01-01",
        "sent": 500,
        "opened": 150,
        "clicked": 60
      }
    ],
    "top_campaigns": [
      {
        "id": "camp_123",
        "name": "New Year Sale",
        "open_rate": 35.2,
        "click_rate": 15.8
      }
    ]
  }
}

Get Provider Analytics

GET /analytics/providers

Get Geographic Analytics

GET /analytics/geographic

Get Device Analytics

GET /analytics/devices

Webhooks

List Webhooks

GET /webhooks

Create Webhook

POST /webhooks

Request Body:

{
  "name": "Campaign Events",
  "url": "https://your-app.com/webhooks/email",
  "events": ["campaign.sent", "campaign.opened", "campaign.clicked"],
  "secret": "your-webhook-secret",
  "enabled": true
}

Available Events:

campaign.created
campaign.sent
campaign.opened
campaign.clicked
contact.subscribed
contact.unsubscribed
email.bounced
email.delivered

Update Webhook

PUT /webhooks/{id}

Delete Webhook

DELETE /webhooks/{id}

Test Webhook

POST /webhooks/{id}/test

Webhook Payloads

Campaign Sent

{
  "event": "campaign.sent",
  "timestamp": "2024-01-15T10:00:00Z",
  "data": {
    "campaign_id": "camp_123456",
    "campaign_name": "Welcome Campaign",
    "sent_at": "2024-01-15T10:00:00Z",
    "recipient_count": 1000,
    "provider": "zeptomail"
  }
}

Email Opened

{
  "event": "campaign.opened",
  "timestamp": "2024-01-15T10:05:00Z",
  "data": {
    "campaign_id": "camp_123456",
    "contact_id": "contact_789",
    "contact_email": "john@example.com",
    "opened_at": "2024-01-15T10:05:00Z",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)",
    "ip_address": "192.168.1.1",
    "location": {
      "country": "US",
      "city": "New York"
    }
  }
}

Email Clicked

{
  "event": "campaign.clicked",
  "timestamp": "2024-01-15T10:10:00Z",
  "data": {
    "campaign_id": "camp_123456",
    "contact_id": "contact_789",
    "contact_email": "john@example.com",
    "clicked_at": "2024-01-15T10:10:00Z",
    "url": "https://example.com/special-offer",
    "clicked_url": "https://mails.nssoftwaresolutions.in/click/abc123",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "ip_address": "192.168.1.2"
  }
}

SDKs & Libraries

JavaScript/TypeScript SDK

npm install @flowcampaign/sdk

Usage:

import { FlowCampaign } from '@flowcampaign/sdk';

const client = new FlowCampaign({
  apiKey: 'your-api-key',
  baseUrl: 'https://mails.nssoftwaresolutions.in'
});

// Send email
const result = await client.email.send({
  to: 'recipient@example.com',
  subject: 'Test Email',
  html: '<h1>Hello</h1>'
});

// Create campaign
const campaign = await client.campaigns.create({
  name: 'New Campaign',
  subject: 'Welcome!',
  audience: { type: 'list', list_id: 'list_123' }
});

Python SDK

pip install flowcampaign-python

Usage:

from flowcampaign import FlowCampaign

client = FlowCampaign(api_key="your-api-key")

# Send email
response = client.email.send(
    to="recipient@example.com",
    subject="Test Email",
    html="<h1>Hello</h1>"
)

# Get analytics
analytics = client.analytics.overall(
    start_date="2024-01-01",
    end_date="2024-01-31"
)

PHP SDK

composer require flowcampaign/php-sdk

Usage:

use FlowCampaign\Client;

$client = new Client('your-api-key');

// Send email
$result = $client->email()->send([
    'to' => 'recipient@example.com',
    'subject' => 'Test Email',
    'html' => '<h1>Hello</h1>'
]);

// List campaigns
$campaigns = $client->campaigns()->list([
    'page' => 1,
    'limit' => 20
]);

Examples

Complete Campaign Workflow

// 1. Create contact list
const list = await client.lists.create({
  name: 'Newsletter Subscribers',
  description: 'Monthly newsletter audience'
});

// 2. Add contacts
await client.contacts.import({
  list_id: list.id,
  file: csvData,
  tags: ['newsletter']
});

// 3. Create template
const template = await client.templates.create({
  name: 'Monthly Newsletter',
  subject: '{{month}} Newsletter - {{company}}',
  content: newsletterHtml,
  variables: ['month', 'company']
});

// 4. Create campaign
const campaign = await client.campaigns.create({
  name: 'January Newsletter',
  subject: 'January Newsletter - Example Corp',
  template_id: template.id,
  audience: { type: 'list', list_id: list.id },
  schedule: { type: 'scheduled', date: '2024-01-20T10:00:00Z' }
});

// 5. Send campaign
await client.campaigns.send(campaign.id, { confirm: true });

// 6. Monitor analytics
const analytics = await client.campaigns.analytics(campaign.id);

Webhook Handler Example

// Express.js webhook handler
app.post('/webhooks/email', async (req, res) => {
  const signature = req.headers['x-flowcampaign-signature'];
  const payload = req.body;
  
  // Verify signature
  const isValid = verifySignature(signature, payload, WEBHOOK_SECRET);
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  const { event, data } = payload;
  
  switch (event) {
    case 'campaign.opened':
      // Update user engagement in your database
      await updateUserEngagement(data.contact_email, 'email_opened');
      break;
      
    case 'campaign.clicked':
      // Track conversion
      await trackConversion(data.contact_email, data.url);
      break;
      
    case 'contact.unsubscribed':
      // Update subscription status
      await updateSubscription(data.contact_email, false);
      break;
  }
  
  res.status(200).send('OK');
});

Best Practices

1. Error Handling

try {
  const result = await client.campaigns.send(campaignId);
} catch (error) {
  if (error.code === 'RATE_LIMITED') {
    // Implement exponential backoff
    await sleep(1000 * Math.pow(2, retryCount));
    retryCount++;
  } else if (error.code === 'VALIDATION_ERROR') {
    // Handle validation errors
    console.error('Validation errors:', error.details);
  }
}

2. Batch Operations

// Use bulk endpoints for large operations
await client.email.bulk({
  recipients: largeRecipientList,
  subject: 'Bulk Email',
  html: templateHtml,
  send_in_parallel: true,
  batch_size: 100
});

3. Webhook Security

// Always verify webhook signatures
function verifySignature(signature, payload, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const expected = hmac.update(JSON.stringify(payload)).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

4. Performance Optimization

// Use pagination for large datasets
let page = 1;
let allContacts = [];

while (true) {
  const response = await client.contacts.list({ page, limit: 100 });
  allContacts = allContacts.concat(response.data.contacts);
  
  if (page >= response.data.pagination.pages) break;
  page++;
}

Testing

Test API Key

Use the test endpoint to verify your API key:

curl -X GET https://mails.nssoftwaresolutions.in/api \
  -H "Authorization: Bearer YOUR_API_KEY"

Sandbox Mode

For testing, use the sandbox provider that doesn't send actual emails:

{
  "provider": "sandbox",
  "from_email": "test@example.com",
  "from_name": "Test Sender"
}

Need Help? Check our Troubleshooting Guide or contact our API Support.

FlowCampaign's API is designed to be intuitive and powerful, enabling seamless integration with your applications.

Base URL​

Authentication​

Getting API Keys​

Authentication Header​

Rate Limiting​

Response Format​

Error Responses​

Common Error Codes​

Endpoints​

Authentication​

Get API Status​

Campaigns​

List Campaigns​

Get Campaign Details​

Create Campaign​

Update Campaign​

Send Campaign​

Cancel Campaign​

Get Campaign Analytics​

Contacts​

List Contacts​

Get Contact​

Create Contact​

Update Contact​

Delete Contact​

Import Contacts (Bulk)​

Export Contacts​

Lists​

List Contact Lists​

Create List​

Update List​

Delete List​

Templates​

List Templates​

Get Template​

Create Template​

Update Template​

Delete Template​

Preview Template​

Email Sending​

Send Single Email​

Send Bulk Emails​

Analytics​

Get Overall Analytics​

Get Provider Analytics​

Get Geographic Analytics​

Get Device Analytics​

Webhooks​

List Webhooks​

Create Webhook​

Update Webhook​

Delete Webhook​

Test Webhook​

Webhook Payloads​

Campaign Sent​

Email Opened​

Email Clicked​

SDKs & Libraries​

JavaScript/TypeScript SDK​

Python SDK​

PHP SDK​

Examples​

Complete Campaign Workflow​

Webhook Handler Example​

Best Practices​

1. Error Handling​

2. Batch Operations​

3. Webhook Security​

4. Performance Optimization​

Testing​

Test API Key​

Sandbox Mode​

Base URL

Authentication

Getting API Keys

Authentication Header

Rate Limiting

Response Format

Error Responses

Common Error Codes

Endpoints

Authentication

Get API Status

Campaigns

List Campaigns

Get Campaign Details

Create Campaign

Update Campaign

Send Campaign

Cancel Campaign

Get Campaign Analytics

Contacts

List Contacts

Get Contact

Create Contact

Update Contact

Delete Contact

Import Contacts (Bulk)

Export Contacts

Lists

List Contact Lists

Create List

Update List

Delete List

Templates

List Templates

Get Template

Create Template

Update Template

Delete Template

Preview Template

Email Sending

Send Single Email

Send Bulk Emails

Analytics

Get Overall Analytics

Get Provider Analytics

Get Geographic Analytics

Get Device Analytics

Webhooks

List Webhooks

Create Webhook

Update Webhook

Delete Webhook

Test Webhook

Webhook Payloads

Campaign Sent

Email Opened

Email Clicked

SDKs & Libraries

JavaScript/TypeScript SDK

Python SDK

PHP SDK

Examples

Complete Campaign Workflow

Webhook Handler Example

Best Practices

1. Error Handling

2. Batch Operations

3. Webhook Security

4. Performance Optimization

Testing

Test API Key

Sandbox Mode