# Campaigns

NOTE

The URI for the API endpoint is often the same for multiple endpoints, the difference being in HTTP methods.

# List Campaigns

GET https://api.wolfeo.me/v1/campaigns

Returns a paginated list of broadcast campaigns, ordered by most recent first.

# Example Request

curl --request GET "https://api.wolfeo.me/v1/campaigns?status=sent&per_page=25" \
  --header "Authorization: Bearer YOUR_API_KEY"

# Parameters

Parameter	Type	Description
status	string	Filter by status (see possible values below)
period	string	Time range to filter by (see possible values below)
range	string	Custom date range — only used when `period=between`
page	integer	Page number (default: `1`)
per_page	integer	Results per page — max `100` (default: `50`)

# Possible values for `status`

Value	Description
`draft`	Not yet sent
`sending`	Currently being sent
`sent`	Sent successfully
`scheduled`	Scheduled for later
`error`	Sending failed

# Sample Return

{
    "success": true,
    "data": [
        {
            "id": 42,
            "name": "June Newsletter",
            "subject": "What's new this month 🎉",
            "from_name": "John",
            "from_email": "john@example.com",
            "status": "sent",
            "sent_to": 1200,
            "recipients_count": 1200,
            "sent_at": "2024-06-01T10:00:00.000000Z",
            "scheduled_for": null,
            "created_at": "2024-05-28T09:00:00.000000Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 3,
        "per_page": 50,
        "total": 142
    }
}

# Possible Errors

Code	HTTP	Description
INVALID_STATUS	400	Invalid `status` value
INVALID_PERIOD	400	Invalid `period` or missing `range`

# Retrieve Campaign

GET https://api.wolfeo.me/v1/campaign

# Example Request

curl --request GET "https://api.wolfeo.me/v1/campaign?campaign_id=42" \
  --header "Authorization: Bearer YOUR_API_KEY"

# Parameters

Parameter	Type	Description
campaign_id*	integer	The campaign ID

* denotes a required parameter

# Sample Return

{
    "success": true,
    "data": {
        "id": 42,
        "name": "June Newsletter",
        "subject": "What's new this month 🎉",
        "from_name": "John",
        "from_email": "john@example.com",
        "status": "sent",
        "sent_to": 1200,
        "recipients_count": 1200,
        "sent_at": "2024-06-01T10:00:00.000000Z",
        "scheduled_for": null,
        "created_at": "2024-05-28T09:00:00.000000Z"
    }
}

# Possible Errors

Code	HTTP	Description
NOT_FOUND	404	Campaign not found

# Retrieve Campaign Stats

GET https://api.wolfeo.me/v1/campaign-stats

Returns send statistics for a campaign. Stats are read from Redis in real time.

# Example Request

curl --request GET "https://api.wolfeo.me/v1/campaign-stats?campaign_id=42" \
  --header "Authorization: Bearer YOUR_API_KEY"

# Parameters

Parameter	Type	Description
campaign_id*	integer	The campaign ID

* denotes a required parameter

# Sample Return

{
    "success": true,
    "data": {
        "sent_to": 1200,
        "opens": 480,
        "clicks": 192,
        "unsubscribes": 3,
        "open_rate": 40.0,
        "click_rate": 16.0,
        "unsubscribe_rate": 0.3
    }
}

# Possible Errors

Code	HTTP	Description
NOT_FOUND	404	Campaign not found

# Create Campaign

POST https://api.wolfeo.me/v1/campaign

Creates a broadcast campaign as a draft. Use Schedule Campaign to send or schedule it.

# Example Request

curl --request POST "https://api.wolfeo.me/v1/campaign" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "June Newsletter",
    "subject": "What'\''s new this month 🎉",
    "from_name": "John",
    "from_email": "john@example.com"
  }'

# Parameters

Parameter	Type	Description
name*	string	Internal name for the campaign
subject	string	Email subject line
from_name	string	Sender display name
from_email	string	Sender email address

* denotes a required parameter

# Sample Return

HTTP 201 Created

{
    "success": true,
    "data": {
        "campaign_id": 42,
        "name": "June Newsletter",
        "subject": "What's new this month 🎉",
        "from_name": "John",
        "from_email": "john@example.com",
        "status": "draft"
    }
}

# Schedule Campaign

POST https://api.wolfeo.me/v1/campaign-schedule

Schedules an existing draft campaign for sending. The campaign will be sent to all contacts matching the specified filters at the given date and time.

# Example Request

curl --request POST "https://api.wolfeo.me/v1/campaign-schedule" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "campaign_id": 42,
    "scheduled_for": "2025-06-15T14:00:00",
    "incl_tag_ids": [12, 34],
    "excl_tag_ids": [56]
  }'

# Parameters

Parameter	Type	Description
campaign_id*	integer	ID of the draft campaign to schedule
scheduled_for*	string	Send date/time — ISO 8601 or `Y-m-d H:i`, must be in future
send_to_all	boolean	Send to all contacts, ignoring filters (default: `false`)
incl_tag_ids	array	Only send to contacts with these tags
excl_tag_ids	array	Exclude contacts with these tags
incl_sequence_ids	array	Only send to contacts in these sequences
excl_sequence_ids	array	Exclude contacts in these sequences

* denotes a required parameter

Timezone

scheduled_for is interpreted in your account's configured timezone (set in Settings → Email). If no timezone is set, Europe/Paris is used.

# Sample Return

{
    "success": true,
    "data": {
        "campaign_id": 42,
        "status": "scheduled",
        "scheduled_for": "2025-06-15 14:00:00"
    }
}

# Possible Errors

Code	HTTP	Description
NOT_FOUND	404	Campaign not found or already sent
INVALID_DATE	400	`scheduled_for` could not be parsed or is in the past

# Update Campaign

PUT https://api.wolfeo.me/v1/campaign

Updates a draft campaign. Only campaigns with a draft status can be modified.

# Example Request

curl --request PUT "https://api.wolfeo.me/v1/campaign" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "campaign_id": 42,
    "subject": "Updated subject line",
    "from_name": "Jane"
  }'

# Parameters

Parameter	Type	Description
campaign_id*	integer	The campaign ID to update
name	string	Internal name for the campaign
subject	string	Email subject line
from_name	string	Sender display name
from_email	string	Sender email address

* denotes a required parameter

# Sample Return

{
    "success": true,
    "data": {
        "campaign_id": 42,
        "name": "June Newsletter",
        "subject": "Updated subject line",
        "from_name": "Jane",
        "from_email": "john@example.com",
        "status": "draft",
        "updated": true
    }
}

# Possible Errors

Code	HTTP	Description
NOT_FOUND	404	Campaign not found or not a draft

# Delete Campaign

DELETE https://api.wolfeo.me/v1/campaign

Permanently deletes a draft campaign. Scheduled campaigns cannot be deleted — cancel the schedule first.

# Example Request

curl --request DELETE "https://api.wolfeo.me/v1/campaign" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"campaign_id": 42}'

# Parameters

Parameter	Type	Description
campaign_id*	integer	The campaign ID to delete

* denotes a required parameter

# Sample Return

{
    "success": true,
    "data": {
        "deleted": true
    }
}

# Possible Errors

Code	HTTP	Description
NOT_FOUND	404	Campaign not found
CAMPAIGN_SCHEDULED	409	Campaign is scheduled and cannot be deleted

# Send Campaign Immediately

POST https://api.wolfeo.me/v1/campaign-send

Sends an existing draft campaign immediately to the specified audience. Use Schedule Campaign to send at a future date instead.

# Example Request

curl --request POST "https://api.wolfeo.me/v1/campaign-send" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "campaign_id": 42,
    "incl_tag_ids": [12, 34],
    "excl_tag_ids": [56]
  }'

# Parameters

Parameter	Type	Description
campaign_id*	integer	ID of the draft campaign to send
send_to_all	boolean	Send to all contacts, ignoring filters (default: `false`)
incl_tag_ids	array	Only send to contacts with these tags
excl_tag_ids	array	Exclude contacts with these tags
incl_sequence_ids	array	Only send to contacts in these sequences
excl_sequence_ids	array	Exclude contacts in these sequences

* denotes a required parameter

# Sample Return

{
    "success": true,
    "data": {
        "campaign_id": 42,
        "status": "sending"
    }
}

# Possible Errors

Code	HTTP	Description
NOT_FOUND	404	Campaign not found or already sent

# What's next

Contacts — manage contacts and their email stats
Sequences — create and manage automated sequences

← Sequences Funnels →

# Campaigns

# List Campaigns

# Example Request

# Parameters

# Possible values for status

# Sample Return

# Possible Errors

# Retrieve Campaign

# Example Request

# Parameters

# Sample Return

# Possible Errors

# Retrieve Campaign Stats

# Example Request

# Parameters

# Sample Return

# Possible Errors

# Create Campaign

# Example Request

# Parameters

# Sample Return

# Schedule Campaign

# Example Request

# Parameters

# Sample Return

# Possible Errors

# Update Campaign

# Example Request

# Parameters

# Sample Return

# Possible Errors

# Delete Campaign

# Example Request

# Parameters

# Sample Return

# Possible Errors

# Send Campaign Immediately

# Example Request

# Parameters

# Sample Return

# Possible Errors

# What's next

# Possible values for `status`