← Back to Documentation

API Reference

Complete reference for all Gclap API endpoints. All requests require authentication.

Base URL

http://localhost:8000/api/v1/

All API endpoints are relative to this base URL. For production, use your domain.

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Security: Keep your API keys secure. Never share them in public repositories or client-side code.

Email Endpoints

POST
/emails/send/

Send Email

Send a single transactional or marketing email to one recipient.

Request Body

tostringrequired

Recipient email address

subjectstringrequired

Email subject line

htmlstring

HTML email body

textstring

Plain text email body

from_emailstring

Sender email (uses default if not provided)

from_namestring

Sender name

reply_tostring

Reply-to email address

template_iduuid

Template ID to use

template_dataobject

Variables for template rendering

attachmentsarray

List of attachment objects

tagsarray

Tags for categorizing emails

Response Example

{
  "id": "uuid",
  "status": "queued",
  "message": "Email queued for sending",
  "message_id": "unique-message-id"
}
POST
/emails/send-batch/

Send Batch Emails

Send multiple emails in a single request. Efficient for bulk sending.

Request Body

emailsarrayrequired

Array of email objects (same structure as /send/)

Response Example

{
  "queued": 150,
  "failed": 0,
  "message": "Batch emails queued successfully"
}
GET
/emails/

List Emails

Get a list of sent emails with filtering and pagination.

Query Parameters

pageinteger

Page number (default: 1)

page_sizeinteger

Items per page (default: 20, max: 100)

statusstring

Filter by status: queued, sent, delivered, bounced, failed

from_datedate

Filter emails sent after this date

to_datedate

Filter emails sent before this date

Response Example

{
  "count": 1250,
  "next": "http://localhost:8000/api/v1/emails/?page=2",
  "previous": null,
  "results": [
    {
      "id": "uuid",
      "to": "user@example.com",
      "subject": "Welcome!",
      "status": "delivered",
      "sent_at": "2026-01-25T10:30:00Z"
    }
  ]
}
GET
/emails/{id}/

Get Email Details

Retrieve detailed information about a specific email, including events.

Response Example

{
  "id": "uuid",
  "to": "user@example.com",
  "subject": "Welcome!",
  "status": "delivered",
  "sent_at": "2026-01-25T10:30:00Z",
  "delivered_at": "2026-01-25T10:30:15Z",
  "opened_at": "2026-01-25T11:00:00Z",
  "events": [
    {
      "type": "sent",
      "timestamp": "2026-01-25T10:30:00Z"
    },
    {
      "type": "delivered",
      "timestamp": "2026-01-25T10:30:15Z"
    },
    {
      "type": "opened",
      "timestamp": "2026-01-25T11:00:00Z"
    }
  ]
}

Contact Endpoints

GET
/contacts/

List Contacts

Get all contacts in your organization with search and filtering.

Query Parameters

pageinteger

Page number

searchstring

Search by email, first name, or last name

statusstring

Filter by status: active, unsubscribed, bounced

listuuid

Filter by list ID

sourcestring

Filter by source: manual, import, api, signup_form

Response Example

{
  "count": 5420,
  "results": [
    {
      "id": "uuid",
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "status": "active",
      "created_at": "2026-01-20T10:00:00Z"
    }
  ]
}
POST
/contacts/

Create Contact

Add a new contact to your organization.

Request Body

emailstringrequired

Contact email address (must be unique)

first_namestring

First name

last_namestring

Last name

custom_fieldsobject

Custom field values

tagsarray

Tags to assign

listsarray

List IDs to add contact to

Response Example

{
  "id": "uuid",
  "email": "john@example.com",
  "first_name": "John",
  "status": "active",
  "created_at": "2026-01-25T10:30:00Z"
}
POST
/contacts/bulk-create/

Bulk Create Contacts

Create multiple contacts in a single request.

Request Body

contactsarrayrequired

Array of contact objects

Response Example

{
  "created": 95,
  "errors": 5,
  "total_created": 95,
  "total_errors": 5
}
POST
/contacts/import-csv/

Import Contacts from CSV

Upload a CSV file to import contacts in bulk.

Request Body

filefilerequired

CSV file with contact data

field_mappingobjectrequired

Map CSV columns to contact fields

list_iduuid

Add imported contacts to this list

update_existingboolean

Update existing contacts (default: true)

Response Example

{
  "imported": 1500,
  "updated": 200,
  "skipped": 50,
  "errors": 10
}
GET
/contacts/{id}/

Get Contact

Retrieve detailed information about a specific contact.

Response Example

{
  "id": "uuid",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "status": "active",
  "custom_fields": {
    "company": "Acme Inc"
  },
  "tags": [
    "vip",
    "customer"
  ],
  "lists": [
    "uuid1",
    "uuid2"
  ],
  "engagement_score": 85,
  "last_emailed_at": "2026-01-24T15:00:00Z"
}
PATCH
/contacts/{id}/

Update Contact

Update contact information. Only include fields you want to change.

Request Body

first_namestring

Updated first name

last_namestring

Updated last name

custom_fieldsobject

Updated custom fields

DELETE
/contacts/{id}/

Delete Contact

Permanently delete a contact and all associated data.

Campaign Endpoints

GET
/campaigns/

List Campaigns

Get all marketing campaigns with filtering options.

Query Parameters

statusstring

Filter by status: draft, scheduled, sending, sent, paused

typestring

Filter by type: regular, ab_test

Response Example

{
  "count": 45,
  "results": [
    {
      "id": "uuid",
      "name": "January Newsletter",
      "status": "sent",
      "sent_count": 5000,
      "open_rate": 0.28,
      "click_rate": 0.05,
      "sent_at": "2026-01-15T09:00:00Z"
    }
  ]
}
POST
/campaigns/

Create Campaign

Create a new marketing campaign.

Request Body

namestringrequired

Campaign name

subjectstringrequired

Email subject line

from_emailstringrequired

Sender email

from_namestringrequired

Sender name

html_contentstring

HTML email body

template_iduuid

Template to use

list_idsarrayrequired

Lists to send to

segment_idsarray

Segments to filter by

Response Example

{
  "id": "uuid",
  "name": "January Newsletter",
  "status": "draft",
  "created_at": "2026-01-25T10:30:00Z"
}
POST
/campaigns/{id}/send/

Send Campaign

Start sending a campaign immediately to all recipients.

Response Example

{
  "message": "Campaign sending started",
  "campaign": {
    "id": "uuid",
    "status": "sending",
    "estimated_recipients": 5000
  }
}
POST
/campaigns/{id}/schedule/

Schedule Campaign

Schedule a campaign to be sent at a specific time.

Request Body

scheduled_atdatetimerequired

When to send (ISO 8601 format)

Response Example

{
  "id": "uuid",
  "status": "scheduled",
  "scheduled_at": "2026-01-26T09:00:00Z"
}
POST
/campaigns/{id}/pause/

Pause Campaign

Pause a campaign that is currently sending.

GET
/campaigns/{id}/stats/

Get Campaign Stats

Get detailed statistics for a campaign.

Response Example

{
  "sent": 5000,
  "delivered": 4950,
  "opened": 1400,
  "clicked": 250,
  "bounced": 50,
  "unsubscribed": 15,
  "open_rate": 0.28,
  "click_rate": 0.05,
  "bounce_rate": 0.01
}

Analytics Endpoints

GET
/analytics/dashboard/

Dashboard Stats

Get overview statistics for your account.

Query Parameters

daysinteger

Number of days to include (default: 30)

Response Example

{
  "period_days": 30,
  "emails_sent": 15000,
  "emails_delivered": 14850,
  "emails_opened": 4200,
  "emails_clicked": 750,
  "open_rate": 0.28,
  "click_rate": 0.05,
  "bounce_rate": 0.01,
  "unsubscribes": 45,
  "total_contacts": 8500,
  "active_campaigns": 3
}
GET
/analytics/charts/email-volume/

Email Volume Chart

Get daily email volume data for charting.

Query Parameters

daysinteger

Number of days (default: 30)

Response Example

[
  {
    "date": "2026-01-25",
    "emails_sent": 500,
    "emails_delivered": 495,
    "unique_opens": 140,
    "unique_clicks": 25
  }
]
GET
/analytics/events/

Email Events

Get detailed email events (opens, clicks, bounces, etc.).

Query Parameters

typestring

Event type: sent, delivered, opened, clicked, bounced, unsubscribed

emailuuid

Filter by email ID

contactuuid

Filter by contact ID

from_datedate

Events after this date

to_datedate

Events before this date

Response Example

{
  "count": 1500,
  "results": [
    {
      "id": "uuid",
      "event_type": "opened",
      "timestamp": "2026-01-25T11:00:00Z",
      "email": "uuid",
      "contact": "uuid",
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "country": "US",
      "device_type": "desktop"
    }
  ]
}
GET
/analytics/engagement/

Contact Engagement

Get engagement scores for contacts.

Query Parameters

levelstring

Filter by level: very_high, high, medium, low, very_low

min_scoreinteger

Minimum engagement score (0-100)

Response Example

{
  "count": 8500,
  "results": [
    {
      "id": "uuid",
      "contact": "uuid",
      "contact_email": "john@example.com",
      "score": 85,
      "engagement_level": "very_high",
      "emails_received": 50,
      "emails_opened": 45,
      "emails_clicked": 20,
      "last_open_at": "2026-01-24T15:00:00Z"
    }
  ]
}

Automation Endpoints

GET
/automation/

List Workflows

Get all automation workflows.

Query Parameters

statusstring

Filter by status: active, paused, draft

Response Example

{
  "count": 12,
  "results": [
    {
      "id": "uuid",
      "name": "Welcome Series",
      "status": "active",
      "trigger_type": "contact_created",
      "enrolled_count": 1500,
      "completed_count": 1200
    }
  ]
}
POST
/automation/

Create Workflow

Create a new automation workflow.

Request Body

namestringrequired

Workflow name

trigger_typestringrequired

Trigger: contact_created, tag_added, list_joined, etc.

trigger_configobject

Trigger configuration

stepsarrayrequired

Workflow steps

POST
/automation/{id}/activate/

Activate Workflow

Activate a workflow to start processing new enrollments.

POST
/automation/{id}/pause/

Pause Workflow

Pause a workflow. Existing enrollments continue, but no new ones are added.

Webhook Endpoints

GET
/webhooks/endpoints/

List Webhooks

Get all configured webhook endpoints.

Response Example

{
  "count": 3,
  "results": [
    {
      "id": "uuid",
      "url": "https://yourapp.com/webhooks/gclap",
      "events": [
        "email.opened",
        "email.clicked"
      ],
      "is_active": true,
      "created_at": "2026-01-20T10:00:00Z"
    }
  ]
}
POST
/webhooks/endpoints/

Create Webhook

Register a new webhook endpoint to receive event notifications.

Request Body

urlstringrequired

Your webhook URL (must be HTTPS)

eventsarrayrequired

Events to subscribe to

descriptionstring

Webhook description

secretstring

Secret for signature verification (auto-generated if not provided)

Response Example

{
  "id": "uuid",
  "url": "https://yourapp.com/webhooks/gclap",
  "events": [
    "email.opened",
    "email.clicked"
  ],
  "secret": "whsec_xxxxxxxxxxxxx",
  "is_active": true
}
POST
/webhooks/endpoints/{id}/test/

Test Webhook

Send a test event to verify your webhook is working.

Response Example

{
  "message": "Test webhook sent",
  "delivery_id": "uuid"
}
POST
/webhooks/endpoints/{id}/rotate-secret/

Rotate Webhook Secret

Generate a new secret for webhook signature verification.

Response Example

{
  "message": "Secret rotated successfully",
  "secret": "whsec_new_secret_here",
  "warning": "Store this secret securely. It cannot be retrieved again."
}

API Key Endpoints

GET
/accounts/api-keys/

List API Keys

Get all API keys for your organization.

Response Example

{
  "count": 5,
  "results": [
    {
      "id": "uuid",
      "name": "Production Server",
      "prefix": "gclap_live_abc",
      "scopes": [
        "*"
      ],
      "is_active": true,
      "last_used_at": "2026-01-25T10:00:00Z",
      "created_at": "2026-01-01T10:00:00Z"
    }
  ]
}
POST
/accounts/api-keys/

Create API Key

Generate a new API key with specific permissions.

Request Body

namestringrequired

Key name for identification

scopesarray

Permission scopes (default: all)

expires_atdatetime

Expiration date

allowed_ipsarray

IP allowlist for extra security

Response Example

{
  "id": "uuid",
  "name": "Production Server",
  "key": "gclap_live_xxxxxxxxxxxxxxxxxxxxxxxxxx",
  "prefix": "gclap_live_abc",
  "scopes": [
    "*"
  ],
  "created_at": "2026-01-25T10:30:00Z",
  "warning": "Store this key securely. It will not be shown again."
}
POST
/accounts/api-keys/{id}/revoke/

Revoke API Key

Immediately revoke an API key. This cannot be undone.

Response Example

{
  "message": "API key revoked successfully"
}
POST
/accounts/api-keys/{id}/rotate/

Rotate API Key

Create a new key and set a grace period for the old key.

Request Body

grace_period_hoursintegerrequired

Hours before old key expires (1-168)

Response Example

{
  "new_key": {
    "id": "uuid",
    "key": "gclap_live_new_key_here",
    "name": "Production Server"
  },
  "old_key": {
    "id": "uuid",
    "grace_period_until": "2026-01-26T10:30:00Z"
  },
  "message": "Key rotated successfully. Old key will remain valid until specified time."
}

Error Responses

All errors follow a consistent format with HTTP status codes and detailed error information.

400

Bad Request

Invalid request data or parameters.

{
  "error": {
    "code": "E1001",
    "message": "Invalid email address",
    "details": {
      "field": "to",
      "value": "invalid-email"
    },
    "request_id": "req_xxxxx",
    "timestamp": "2026-01-25T10:30:00Z"
  }
}
401

Unauthorized

Missing or invalid API key.

{
  "error": {
    "code": "E1003",
    "message": "Invalid authentication token",
    "documentation_url": "https://docs.gclap.io/errors/E1003"
  }
}
403

Forbidden

You don't have permission to access this resource.

{
  "error": {
    "code": "E1004",
    "message": "Insufficient permissions",
    "details": {
      "required_scope": "contacts:write"
    }
  }
}
404

Not Found

The requested resource doesn't exist.

{
  "error": {
    "code": "E1005",
    "message": "Resource not found",
    "details": {
      "resource_type": "contact",
      "resource_id": "uuid"
    }
  }
}
429

Rate Limit Exceeded

You've exceeded the rate limit for your plan.

{
  "error": {
    "code": "E1006",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 1000,
      "remaining": 0,
      "reset_at": "2026-01-25T11:00:00Z"
    }
  }
}
500

Internal Server Error

Something went wrong on our end. We've been notified.

{
  "error": {
    "code": "E5000",
    "message": "Internal server error",
    "request_id": "req_xxxxx",
    "documentation_url": "https://docs.gclap.io/errors/E5000"
  }
}

Rate Limits

Rate limits are applied per API key. Headers in each response show your current usage.

Free Plan

100

requests per minute

Pro Plan

1,000

requests per minute

Business Plan

5,000

requests per minute

Rate Limit Headers

X-RateLimit-Limit:1000
X-RateLimit-Remaining:995
X-RateLimit-Reset:1706184000

Pagination

List endpoints return paginated results. Use query parameters to control pagination.

Query Parameters

  • page - Page number (default: 1)
  • page_size - Items per page (default: 20, max: 100)

Response Format

{
  "count": 1250,
  "next": "http://localhost:8000/api/v1/contacts/?page=2",
  "previous": null,
  "results": [...]
}

Need Help?

Can't find what you're looking for? We're here to help you integrate successfully.