Getting Started

This guide walks you through connecting to the CampaignOS API and making your first requests.

1. Create Your Account

Sign up at your CampaignOS instance and create a workspace. Each workspace is an isolated environment with its own contacts, campaigns, and settings.

2. Get Your API Key

Navigate to Settings → API Keys in the dashboard, or use the API:


POST /api/workspaces/{workspaceId}/api-keys


{
  "name": "My Integration Key"
}

The response includes your API key — save it securely, it’s only shown once.

See API Keys for full details.

3. Authenticate Requests

Include your API key in the Authorization header:


curl -H "Authorization: Bearer cos_your_api_key_here" \
  https://your-domain.com/api/workspaces/{workspaceId}/contacts

4. Create Your First Contact


curl -X POST \
  -H "Authorization: Bearer cos_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "attributes": { "plan": "pro" }
  }' \
  https://your-domain.com/api/workspaces/{workspaceId}/contacts

See Contacts for all available operations.

5. Build a Segment

Create a dynamic segment to group contacts:


curl -X POST \
  -H "Authorization: Bearer cos_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Users",
    "rules": {
      "operator": "AND",
      "conditions": [
        { "field": "attributes.plan", "operator": "equals", "value": "pro" }
      ]
    }
  }' \
  https://your-domain.com/api/workspaces/{workspaceId}/segments

See Segments for advanced segmentation.

6. Install the Website Script

Add the CampaignOS tracking script to your website for event tracking and on-site personalization:


<script
  src="https://your-domain.com/campaignos.js"
  data-workspace="your-workspace-id"
  async
></script>

See Website Script for full capabilities.

7. Send Your First Message


curl -X POST \
  -H "Authorization: Bearer cos_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "EMAIL",
    "contactId": "ct_abc123",
    "templateId": "tpl_abc123"
  }' \
  https://your-domain.com/api/workspaces/{workspaceId}/messages/send

See Messages for all messaging channels.

What’s Next?

Goal	Resource
Import contacts in bulk	Contacts → CSV Import
Create campaign automations	Campaigns
Set up push notifications	Push Notifications
Configure webhooks	Webhooks
Track campaign performance	Analytics
Manage consent & unsubscription	Compliance