Skip to content
Menu
Live demo

REST API Reference

Complete REST API reference for integrating with WP Outreach programmatically.

Updated December 29, 2025

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/subscribers

Query Parameters:

ParameterTypeDescription
pageintegerPage number (default: 1)
per_pageintegerItems per page (default: 20, max: 100)
searchstringSearch by email or name
statusstringFilter by status (active, pending, unsubscribed, bounced)
list_idintegerFilter by list
tag_idintegerFilter 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/subscribers

Body 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/lists

Response:

{
  "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/tags

Create 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/campaigns

Query Parameters:

ParameterDescription
statusdraft, scheduled, sending, sent, paused
typeone_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}/send

Get Campaign Progress

GET /wp-outreach/v1/campaigns/{id}/progress

Response:

{
  "total": 1000,
  "sent": 450,
  "pending": 550,
  "failed": 0,
  "progress_percent": 45
}

Pause Campaign

POST /wp-outreach/v1/campaigns/{id}/pause

Resume Campaign

POST /wp-outreach/v1/campaigns/{id}/resume

Get Campaign Statistics

GET /wp-outreach/v1/campaigns/{id}/stats

Response:

{
  "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/automations

Get Automation

GET /wp-outreach/v1/automations/{id}

Get Available Triggers

GET /wp-outreach/v1/automations/triggers

Get Available Actions

GET /wp-outreach/v1/automations/actions

Templates

List Templates

GET /wp-outreach/v1/templates

Get 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

Need help?

Can't find what you're looking for or found an error in the docs?

Contact Support
outreach / deploy

Fix your WordPress email.
Ship every message.

SMTP delivery, newsletter campaigns and automation in one plugin. Install in minutes, keep your data on your own server.

$ wp plugin install outreach --activate