List Campaigns

Retrieve a paginated list of campaigns with optional filtering.

Request

GET /campaigns

Query Parameters

All parameters are optional and combined with AND.

Parameter	Type	Default	Description
page	integer	1	Page number (min: 1)
per_page	integer	100	Items per page (min: 1, max: 100)
search	string	-	Partial, case-insensitive match on the campaign name (max 255 characters).
status	string	-	Return only campaigns with this status: draft, scheduled, queued, sending, sent, failed, or canceled (see Statuses).
sort	string	-created_at	Sort order: created_at, updated_at, or name. Prefix with - for descending.

An unknown status, an unsupported sort field, or an out-of-range page / per_page returns 422 VALIDATION_ERROR.

Ordering: Results default to created_at descending (newest first) unless sort is supplied.

Counting matches: every response includes the filtered total in pagination.total. To get only a count, request per_page=1 with your filters and read pagination.total.

Example Requests

List the most recently created campaigns:

curl -X GET "https://email.easy.tools/api/v1/campaigns?page=1&per_page=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Drafts only, ordered by name:

curl -X GET "https://email.easy.tools/api/v1/campaigns?status=draft&sort=name" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Count the campaigns that have been sent:

curl -X GET "https://email.easy.tools/api/v1/campaigns?status=sent&per_page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response

Success Response (200 OK)

{
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Spring Sale",
      "status": "sent",
      "subject": "Up to 40% off this week",
      "from_name": "Acme",
      "language": "en",
      "scheduled_at": null,
      "recipients_count": 1284,
      "created_at": "2026-03-01T09:00:00Z",
      "updated_at": "2026-03-02T11:15:00Z"
    },
    {
      "uuid": "660e8400-e29b-41d4-a716-446655440001",
      "name": "June Newsletter",
      "status": "draft",
      "subject": null,
      "from_name": "Acme",
      "language": null,
      "scheduled_at": null,
      "recipients_count": 0,
      "created_at": "2026-06-20T14:30:00Z",
      "updated_at": "2026-06-20T14:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 2
  }
}

Response Fields

Field	Type	Description
uuid	string	Campaign's unique identifier
name	string	Campaign name
status	string	Current status: draft, scheduled, queued, sending, sent, failed, or canceled
subject	string|null	Email subject line. null until set.
from_name	string|null	Sender display name. null until set.
language	string|null	ISO 639-1 language code (2 characters). null until set.
scheduled_at	string|null	ISO 8601 timestamp (UTC) the campaign is scheduled to send. null when not scheduled.
recipients_count	integer	Number of recipients the campaign was sent to. 0 for campaigns that have not been sent yet.
created_at	string	ISO 8601 timestamp (UTC)
updated_at	string	ISO 8601 timestamp (UTC)

Pagination Object

Field	Type	Description
current_page	integer	Current page number
per_page	integer	Number of items per page
total	integer	Total number of campaigns

Error Responses

Validation Error (422 Unprocessable Entity)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid",
    "details": {
      "status": ["The selected status is invalid."]
    }
  }
}