Campaigns API

Create, manage, and analyze phishing campaigns programmatically

Overview

The Campaigns API allows you to programmatically create, manage, and monitor phishing simulation campaigns. You can automate campaign creation, retrieve results, and integrate PhishFortress campaigns into your security workflows.

Required Permissions

To use the Campaigns API, your API key must have campaigns:read and campaigns:write permissions.

API Endpoints

The Campaigns API provides endpoints for complete campaign lifecycle management.

List Campaigns

Retrieve all campaigns with optional filtering

GET/v1/campaigns

Query Parameters

Parameter	Type	Description
status	string	Filter by campaign status (draft, active, completed)
limit	integer	Number of results to return (default: 50, max: 100)
offset	integer	Number of results to skip for pagination

Create Campaign

Create a new phishing simulation campaign

POST/v1/campaigns

Request Body Example

{
  "name": "Q1 Security Awareness Campaign",
  "description": "Quarterly phishing simulation for all employees",
  "template_id": "template_123",
  "target_groups": ["finance", "hr", "engineering"],
  "schedule": {
    "start_date": "2024-02-01T09:00:00Z",
    "end_date": "2024-02-15T17:00:00Z",
    "send_immediately": false
  },
  "settings": {
    "track_clicks": true,
    "track_credentials": true,
    "enable_training": true,
    "training_delay_minutes": 5
  }
}

Get Campaign Details

Retrieve detailed information about a specific campaign

GET/v1/campaigns/{id}

Response Example

{
  "id": "campaign_123",
  "name": "Q1 Security Awareness Campaign",
  "status": "active",
  "created_at": "2024-01-15T10:00:00Z",
  "started_at": "2024-02-01T09:00:00Z",
  "statistics": {
    "emails_sent": 1250,
    "emails_opened": 892,
    "links_clicked": 156,
    "credentials_submitted": 23,
    "users_reported": 67
  },
  "template": {
    "id": "template_123",
    "name": "Password Reset Notification"
  }
}

Campaign Lifecycle

Understanding the campaign lifecycle helps you manage campaigns effectively through the API.

Campaign States

Draft

Campaign is created but not yet scheduled or launched. Can be edited freely.

Scheduled

Campaign is scheduled to start at a future date. Limited editing allowed.

Active

Campaign is currently running. Emails are being sent and results are being collected.

Completed

Campaign has finished. All emails sent and final results are available.

Cancelled

Campaign was stopped before completion. Partial results may be available.

Campaign Results & Analytics

Retrieve detailed campaign results and analytics data for reporting and analysis.

Get Campaign Results

Retrieve detailed results and analytics for a campaign

GET/v1/campaigns/{id}/results

Response Example

{
  "campaign_id": "campaign_123",
  "summary": {
    "total_recipients": 1250,
    "emails_sent": 1250,
    "emails_delivered": 1198,
    "emails_opened": 892,
    "links_clicked": 156,
    "credentials_submitted": 23,
    "users_reported": 67,
    "training_completed": 134
  },
  "metrics": {
    "click_rate": 12.5,
    "credential_rate": 1.8,
    "report_rate": 5.4,
    "training_completion_rate": 85.9
  },
  "department_breakdown": [
    {
      "department": "finance",
      "recipients": 45,
      "clicked": 8,
      "reported": 12
    },
    {
      "department": "hr",
      "recipients": 32,
      "clicked": 3,
      "reported": 18
    }
  ],
  "timeline": [
    {
      "timestamp": "2024-02-01T09:00:00Z",
      "event": "campaign_started",
      "count": 1250
    },
    {
      "timestamp": "2024-02-01T09:15:00Z",
      "event": "first_click",
      "user_id": "user_456"
    }
  ]
}

Export Results

Export campaign results in various formats

POST/v1/campaigns/{id}/export

Supported Formats

CSV: Raw data for spreadsheet analysis
PDF: Executive summary report
JSON: Structured data for further processing
Excel: Formatted workbook with charts

Error Handling

The Campaigns API returns specific error codes to help you handle different scenarios.

Common Error Scenarios

Always check the response status code and error message when handling API responses.

Error Code	HTTP Status	Description
CAMPAIGN_NOT_FOUND	404	Campaign with specified ID doesn't exist
INVALID_TEMPLATE	400	Specified template ID is invalid or inactive
INSUFFICIENT_PERMISSIONS	403	API key lacks required campaign permissions
CAMPAIGN_LIMIT_EXCEEDED	429	Maximum number of active campaigns reached

Best Practices

Follow these best practices when working with the Campaigns API.

Campaign Management

Test campaigns first: Always test with a small group before launching to all users
Monitor actively: Check campaign progress regularly, especially in the first hour
Handle errors gracefully: Implement proper error handling and retry logic
Use webhooks: Set up webhooks for real-time notifications instead of polling
Respect rate limits: Don't exceed API rate limits when creating multiple campaigns

Performance Optimization

Batch operations: Use bulk endpoints when creating multiple campaigns
Pagination: Use pagination for large result sets to improve response times
Caching: Cache campaign data that doesn't change frequently
Filtering: Use query parameters to filter results and reduce payload size

Authentication Templates API