REST API Reference
Complete REST API reference for integrating with WP Outreach programmatically.
WP Outreach provides a comprehensive REST API for managing subscribers, campaigns, and automations programmatically. All endpoints use the WordPress REST API infrastructure.
API Basics
Base URL
https://yoursite.com/wp-json/wp-outreach/v1/Authentication
Most endpoints require authentication. Use one of these methods:
Cookie Authentication (for logged-in users)
Include the WordPress nonce in your requests:
// JavaScript
fetch('/wp-json/wp-outreach/v1/subscribers', {
headers: {
'X-WP-Nonce': wpApiSettings.nonce
}
});Application Passwords (WordPress 5.6+)
// cURL
curl -X GET https://yoursite.com/wp-json/wp-outreach/v1/subscribers \
-u "username:application-password"Response Format
All responses are JSON formatted:
{
"success": true,
"data": { ... },
"message": "Optional message"
}Error Responses
{
"code": "rest_forbidden",
"message": "Sorry, you are not allowed to do that.",
"data": {
"status": 403
}
}Subscribers
List Subscribers
GET /wp-outreach/v1/subscribersQuery Parameters:
| Parameter | Type | Description |
|---|---|---|
| page | integer | Page number (default: 1) |
| per_page | integer | Items per page (default: 20, max: 100) |
| search | string | Search by email or name |
| status | string | Filter by status (active, pending, unsubscribed, bounced) |
| list_id | integer | Filter by list |
| tag_id | integer | Filter by tag |
Response:
{
"data": [
{
"id": 1,
"email": "john@example.com",
"first_name": "John",
"last_name": "Doe",
"status": "active",
"source": "form",
"lists": [1, 3],
"tags": [2, 5],
"created_at": "2024-12-27T10:30:00Z"
}
],
"total": 150,
"pages": 8
}Get Single Subscriber
GET /wp-outreach/v1/subscribers/{id}Create Subscriber
POST /wp-outreach/v1/subscribersBody Parameters:
{
"email": "jane@example.com", // required
"first_name": "Jane",
"last_name": "Smith",
"status": "active", // active, pending
"lists": [1, 2], // list IDs
"tags": [3], // tag IDs
"custom_fields": { // optional custom data
"company": "Acme Inc"
}
}Update Subscriber
PUT /wp-outreach/v1/subscribers/{id}Same body parameters as create. Only include fields you want to update.
Delete Subscriber
DELETE /wp-outreach/v1/subscribers/{id}Lists
List All Lists
GET /wp-outreach/v1/listsResponse:
{
"data": [
{
"id": 1,
"name": "Newsletter",
"slug": "newsletter",
"description": "Main newsletter list",
"double_optin": true,
"is_public": true,
"subscriber_count": 1250
}
]
}Create List
POST /wp-outreach/v1/lists
{
"name": "Premium Members",
"description": "Paid subscribers only",
"double_optin": true,
"is_public": false
}Update List
PUT /wp-outreach/v1/lists/{id}Delete List
DELETE /wp-outreach/v1/lists/{id}Tags
List All Tags
GET /wp-outreach/v1/tagsCreate Tag
POST /wp-outreach/v1/tags
{
"name": "VIP Customer",
"color": "#10b981"
}Update Tag
PUT /wp-outreach/v1/tags/{id}Delete Tag
DELETE /wp-outreach/v1/tags/{id}Campaigns
List Campaigns
GET /wp-outreach/v1/campaignsQuery Parameters:
| Parameter | Description |
|---|---|
| status | draft, scheduled, sending, sent, paused |
| type | one_time, scheduled, recurring |
Get Campaign
GET /wp-outreach/v1/campaigns/{id}Create Campaign
POST /wp-outreach/v1/campaigns
{
"name": "January Newsletter",
"type": "one_time",
"subject": "Your January Update",
"preheader": "Check out what is new this month",
"content": "<html>...</html>",
"list_ids": [1, 2],
"tag_ids": [3]
}Send Campaign
POST /wp-outreach/v1/campaigns/{id}/sendGet Campaign Progress
GET /wp-outreach/v1/campaigns/{id}/progressResponse:
{
"total": 1000,
"sent": 450,
"pending": 550,
"failed": 0,
"progress_percent": 45
}Pause Campaign
POST /wp-outreach/v1/campaigns/{id}/pauseResume Campaign
POST /wp-outreach/v1/campaigns/{id}/resumeGet Campaign Statistics
GET /wp-outreach/v1/campaigns/{id}/statsResponse:
{
"total_sent": 1000,
"total_opened": 350,
"unique_opens": 300,
"open_rate": "30%",
"total_clicked": 120,
"unique_clicks": 100,
"click_rate": "10%",
"unsubscribed": 5,
"bounced": 3,
"links": [
{
"url": "https://example.com/offer",
"clicks": 85
}
]
}Automations
List Automations
GET /wp-outreach/v1/automationsGet Automation
GET /wp-outreach/v1/automations/{id}Get Available Triggers
GET /wp-outreach/v1/automations/triggersGet Available Actions
GET /wp-outreach/v1/automations/actionsTemplates
List Templates
GET /wp-outreach/v1/templatesGet Template
GET /wp-outreach/v1/templates/{id}Create Template
POST /wp-outreach/v1/templates
{
"name": "Product Launch",
"subject": "Introducing Our New Product",
"content": "<html>...</html>",
"content_json": { ... }
}Public Endpoints
These endpoints do not require authentication:
Subscribe
POST /wp-outreach/v1/subscribe
{
"email": "newuser@example.com",
"first_name": "New",
"list": "newsletter"
}Confirm Email
GET /wp-outreach/v1/confirm?token={token}Unsubscribe
GET /wp-outreach/v1/unsubscribe?token={token}Rate Limits
The API follows standard WordPress REST API rate limiting. For high-volume integrations, consider:
- Implementing caching on your end
- Using pagination for large datasets
- Batching requests when possible
Code Examples
JavaScript/Fetch
// Get subscribers
const response = await fetch('/wp-json/wp-outreach/v1/subscribers', {
headers: {
'X-WP-Nonce': wpApiSettings.nonce
}
});
const data = await response.json();
// Create subscriber
const newSub = await fetch('/wp-json/wp-outreach/v1/subscribers', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-WP-Nonce': wpApiSettings.nonce
},
body: JSON.stringify({
email: 'test@example.com',
first_name: 'Test',
lists: [1]
})
});PHP/WordPress
// Using wp_remote_get
$response = wp_remote_get(
rest_url('wp-outreach/v1/subscribers'),
[
'headers' => [
'X-WP-Nonce' => wp_create_nonce('wp_rest')
]
]
);
$subscribers = json_decode(wp_remote_retrieve_body($response), true);
// Create subscriber
$response = wp_remote_post(
rest_url('wp-outreach/v1/subscribers'),
[
'headers' => [
'Content-Type' => 'application/json',
'X-WP-Nonce' => wp_create_nonce('wp_rest')
],
'body' => json_encode([
'email' => 'test@example.com',
'lists' => [1]
])
]
);cURL
# List subscribers
curl -X GET "https://yoursite.com/wp-json/wp-outreach/v1/subscribers" \
-u "username:application-password"
# Create subscriber
curl -X POST "https://yoursite.com/wp-json/wp-outreach/v1/subscribers" \
-u "username:application-password" \
-H "Content-Type: application/json" \
-d '{"email":"test@example.com","lists":[1]}'Last updated: December 29, 2025