Dashboard

    Using the REST API

    Noptin extends the WordPress REST API to allow subscriber management. You can query, create, update, or delete newsletter subscribers via this API.

    Authentication

    This API is only available to site admins and users with the manage_noptin capability.

    This means that all requests must be authenticated using either WordPress Application Passwords, OAuth 1.0a Server, or JSON Web Tokens.

    Guide: REST API Authentication

    Base URL

    All API requests should use the below base URL:-

    https://example.com/wp-json/noptin/v1/

    TIP:-

    Replace example.com with your website’s URL.

    Endpoints Overview

    • GET /subscribers – List subscribers.
    • POST /subscribers – Add a new subscriber.
    • PATCH /subscribers – Bulk update subscribers.
    • DELETE /subscribers – Bulk delete subscribers.
    • GET /subscribers/{id} – Retrieve a subscriber by ID.
    • PATCH /subscribers/{id} – Update a subscriber by ID.
    • DELETE /subscribers/{id} – Delete a subscriber by ID.
    • GET /subscribers/email/{email} – Retrieve a subscriber by email.
    • PATCH /subscribers/email/{email} – Update a subscriber by email.
    • DELETE /subscribers/email/{email} – Delete a subscriber by email.

    Add a new subscriber

    POST /subscribers

    Use this endpoint to create a new subscriber.

    Only the email address is required. This endpoint will return an error if the email address is either invalid or already exists.

    Payload Example

    {
  "email": "[email protected]",
  "first_name": "Test",
  "last_name": "User",
  "status": "subscribed",
  "tags": ["beta-user"],
  "custom_field_key": "custom_value",
  "conversion_page": "https:\/\/example.com\/newsletter-signup\/"
}

    TIP:-

    You may include any custom fields registered in Noptin.

    Response

    This endpoint returns a subscriber object.

    {
    "id": 100,
    "name": "Test User",
    "email": "[email protected]",
    "first_name": "Test",
    "last_name": "User",
    "custom_field_key": "custom_value",
    "tags": [
        "beta-user"
    ],
    "status": "pending",
    "source": "manual",
    "ip_address": "1.1.1.1",
    "conversion_page": "https:\/\/example.com\/newsletter-signup\/",
    ...
}

    Get Subscribers

    You can use the REST API to either query multiple subscribers or retrieve a single subscriber.

    List Subscribers

    GET /subscribers

    Use this endpoint to query subscribers using a wide range of filters.

    Query Parameters

    NameTypeDescription
    emailstring/arrayMatch email addressess
    email_notstring/arrayMatch email addresses
    first_namestring/arrayMatch first name(s)
    first_name_notstring/arrayExclude first name(s)
    last_namestring/arrayMatch last name(s)
    last_name_notstring/arrayExclude last name(s)
    tagsarrayFilter by tags
    tags_notarrayExclude by tags
    statusstring/arrayFilter by status
    status_notstring/arrayExclude by status
    sourcestring/arrayFilter by source
    source_notstring/arrayExclude by source
    conversion_pagestring/arrayMatch conversion pages
    conversion_page_notstring/arrayExclude conversion pages
    confirmedbool/intFilter by confirmation status
    date_created_beforestringCreated before a specific date
    date_created_afterstringCreated after a specific date
    date_created_queryobjectA full WP_Date_Query structure
    orderstringSort order: asc or desc
    orderbystringSort by: email, status, first_name, etc.
    per_pageintegerMax results per page (default: 25, maximum: 100)
    searchstringSearch term
    pagedintegerPage number
    includearrayOnly include specific subscriber IDs
    excludearrayExclude specific subscriber IDs
    search_columnsarraySpecify which fields to search in. If not specified, we’ll search in all fields.

    Example

    Get all subscribers tagged with WooCommerce.

    GET https://example.com/wp-json/noptin/v1/subscribers?tags=woocommerce

    Search all active Gmail subscribers who subscribed between 2025-05-01 and 2025-05-14.

    GET https://example.com/wp-json/noptin/v1/subscribers?search=gmail.com&date_created_after=2025-04-30&date_created_before=2025-05-14&status=subscribed

    You can also filter via any custom fields that you’ve specified in Noptin.

    For example,

    Assume you have a custom field called lists, the request below will only return subscribers who are in the customers list.

    GET https://example.com/wp-json/noptin/v1/subscribers?list=customers

    Response

    This endpoint returns an array of subscriber objects.

    [
    {
        "id": 100,
        "name": "Test User",
        "email": "[email protected]",
        "first_name": "Test",
        "last_name": "User",
        "custom_field_key": "custom_value",
        "tags": [
            "beta-user"
        ],
        "status": "pending",
        "source": "manual",
        "ip_address": "1.1.1.1",
        "conversion_page": "https:\/\/example.com\/newsletter-signup\/",
        ...
    },
    ...
]

    Get a single subscriber

    You can retrieve a single subscriber by their ID, email address, or confirmation key.

    Get a subscriber by their ID

    GET /subscribers/email/{id}

    Replace {id} with the actual subscriber’s ID as shown below:-

    GET https://example.com/wp-json/noptin/v1/subscribers/123

    Get a subscriber by their email

    GET /subscribers/email/{email}

    Replace {email} with a URL-encoded version of the email address as shown in the example below:-

    GET https://example.com/wp-json/noptin/v1/subscribers/email/test%40example.com

    %40 is the encoded version of @

    Get a Subscriber by their confirmation key

    GET /subscribers/confirm_key/{confirm_key}

    Replace {confirm_key} with their confirmation key as shown in the example below:-

    GET https://example.com/wp-json/noptin/v1/subscribers/confirm_key/a466b9db1799bfff5ca72c2896471f3f

    Response

    All these endpoints return a subscriber object.

    {
    "id": 100,
    "name": "Test User",
    "email": "[email protected]",
    "first_name": "Test",
    "last_name": "User",
    "custom_field_key": "custom_value",
    "tags": [
        "beta-user"
    ],
    "status": "pending",
    "source": "manual",
    "ip_address": "1.1.1.1",
    "conversion_page": "https:\/\/example.com\/newsletter-signup\/",
    ...
}

    Updating Subscribers

    You can use the REST API to update subscribers either in bulk or only a single subscriber.

    Update subscribers in bulk

    PATCH /subscribers

    Use this endpoint to update subscribers in bulk using a wide range of filters. If you don’t specify any filters, then Noptin will update all subscribers.

    You can specify filters as query parameters, similar to how you specify them when listing subscribers.

    Example Payload

    {
  "tags": ["woocommerce"],
  "bulk_update": {
    "status": "unsubscribed",
    "tags::remove": ["woocommerce"],
    "tags::add": ["ignore"],
    "custom_field_key": "custom field value"
  }
}

    This payload will retrieve all subscribers tagged woocommerce, unsubscribe them, remove the woocommerce tag, add an ignore tag, and then update the value of a custom field.

    Response

    This endpoint returns an object where each key is a subscriber ID and the value is either a success or error response.

    {
    "100": {
        "error": "hizzle_rest_cannot_edit",
        "message": "Sorry, you are not allowed to edit this resource."
    },
    "75": {
        "error": "other_error_code",
        "message": "Some error message"
    },
    "76": {
        "success": true,
        "message": "Record updated successfully."
    }
}

    Update a single subscriber

    You can update a single subscriber by their ID, email address, or confirmation key.

    Update a subscriber by their ID

    POST /subscribers/email/{id}

    Replace {id} with the actual subscriber’s ID as shown below:-

    POST https://example.com/wp-json/noptin/v1/subscribers/123

    Update a subscriber by their email

    POST /subscribers/email/{email}

    Replace {email} with a URL-encoded version of the email address as shown in the example below:-

    POST https://example.com/wp-json/noptin/v1/subscribers/email/test%40example.com

    %40 is the encoded version of @

    Update a subscriber by their confirmation key

    POST /subscribers/confirm_key/{confirm_key}

    Replace {confirm_key} with their confirmation key as shown in the example below:-

    POST https://example.com/wp-json/noptin/v1/subscribers/confirm_key/a466b9db1799bfff5ca72c2896471f3f

    Payload

    All these endpoints expect an object containing the new subscriber details. It only updates the keys that you provide in your payload.

    {
    "name": "Test User",
    "email": "[email protected]",
    "first_name": "Test",
    "last_name": "User",
    "custom_field_key": "custom_value",
    "tags::add": [
        "new-tag"
    ],
   "tags::remove": [
        "some-tag"
    ],
    "status": "subscribed"
    ...
}

    The above payload adds a new tag to the subscriber while removing an existing tag at the same time.

    Response

    All these endpoints return a subscriber object.

    {
    "id": 100,
    "name": "Test User",
    "email": "[email protected]",
    "first_name": "Test",
    "last_name": "User",
    "custom_field_key": "custom_value",
    "tags": [
        "new-tag"
    ],
    "status": "subscribed",
    "source": "manual",
    "ip_address": "1.1.1.1",
    "conversion_page": "https:\/\/example.com\/newsletter-signup\/",
    ...
}

    Deleting Subscribers

    You can use the REST API to delete subscribers either in bulk or only a single subscriber.

    Delete subscribers in bulk

    DELETE /subscribers

    Use this endpoint to delete subscribers in bulk using a wide range of filters. If you don’t specify any filters, then Noptin will delete all subscribers.

    You can specify filters as query parameters, similar to how you specify them when listing subscribers.

    Example URL

    DELETE https://example.com/wp-json/noptin/v1/subscribers?tags=woocommerce

    This will only delete newsletter subscribers tagged with WooCommerce.

    Response

    On success, this endpoint will return no body with the 204 HTTP status code.

    Delete a single subscriber

    You can delete a single subscriber by their ID, email address, or confirmation key.

    Delete a subscriber by their ID

    DELETE /subscribers/email/{id}

    Replace {id} with the actual subscriber’s ID as shown below:-

    DELETE https://example.com/wp-json/noptin/v1/subscribers/123

    Delete a subscriber by their email

    DELETE /subscribers/email/{email}

    Replace {email} with a URL-encoded version of the email address as shown in the example below:-

    DELETE https://example.com/wp-json/noptin/v1/subscribers/email/test%40example.com

    %40 is the encoded version of @

    Delete a subscriber by their confirmation key

    DELETE /subscribers/confirm_key/{confirm_key}

    Replace {confirm_key} with their confirmation key as shown in the example below:-

    DELETE https://example.com/wp-json/noptin/v1/subscribers/confirm_key/a466b9db1799bfff5ca72c2896471f3f

    Response

    On success, this endpoint will return no body with the 204 HTTP status code.

    Subscriber Object

    Most API requests will either return this subscriber object or an array of whose elements are this subscriber object.

    {
    "id": 100,
    "name": "Test User",
    "email": "[email protected]",
    "first_name": "Test",
    "last_name": "User",
    "custom_field_key": "custom_value",
    "tags": [
        "beta-user"
    ],
    "status": "pending",
    "source": "manual",
    "ip_address": "1.1.1.1",
    "conversion_page": "https:\/\/example.com\/newsletter-signup\/",
    "confirmed": false,
    "confirm_key": "a466b9db1799bfff5ca72c2896471f3f",
    "date_created": "2025-05-01T07:26:12+03:00",
    "date_modified": "2025-05-01T09:18:56+03:00",
    "activity": [
        {
            "time": 1746079960,
            "content": "Excecuting automation rule, Trigger: <code>Form Submitted, Action: <code>Send Webhook."
        },
            ...
    ],
    "sent_campaigns": {
        "4991": {
            "time": [
                1746073574
            ],
            "opens": [],
            "clicks": [],
            "unsubscribed": false,
            "bounced": false,
            "complained": false
        },
            ...
    },
    "edit_url": "https:\/\/example.com\/wp-admin\/admin.php?page=noptin-subscribers&hizzlewp_path=%2Fnoptin%2Fsubscribers%2F1",
    "unsubscribe_url": "https:\/\/example.com\/?noptin_ns=unsubscribe&nv=kSX32p0si047aUREyny8483W6bBRF6_TCdLNOg38hLrgz55UFudhHWcQi4K4UjPi",
    "resubscribe_url": "https:\/\/example.com\/?noptin_ns=resubscribe&nv=kSX32p0si047aUREyny8483W6bBRF6_TCdLNOg38hLrgz55UFudhHWcQi4K4UjPi",
    "confirm_subscription_url": "https:\/\/example.com\/?noptin_ns=confirm&nv=kSX32p0si047aUREyny8483W6bBRF6_TCdLNOg38hLrgz55UFudhHWcQi4K4UjPi",
    "manage_preferences_url": "https:\/\/n  optin.test\/?noptin_ns=manage_preferences&nv=kSX32p0si047aUREyny8483W6bBRF6_TCdLNOg38hLrgz55UFudhHWcQi4K4UjPi",
    "send_email_url": "https:\/\/example.com\/wp-admin\/admin.php?page=noptin-email-campaigns&noptin_recipients=100&noptin_email_type=newsletter&noptin_campaign=0&noptin_email_sender=noptin",
    "avatar_url": "https:\/\/secure.gravatar.com\/avatar\/557bce0990e7b69a0ca2df3b90810953a471421127eee487862cd7b79a213577?s=64&r=g",
    "wp_user_id": 1,
    "_links": {
        "self": [
            {
                "href": "https:\/\/example.com\/wp-json\/noptin\/v1\/subscribers\/100",
                "targetHints": {
                    "allow": [
                        "GET",
                        "POST",
                        "PUT",
                        "PATCH",
                        "DELETE"
                    ]
                }
            }
        ],
        "collection": [
            {
                "href": "https:\/\/example.com\/wp-json\/noptin\/v1\/subscribers"
            }
        ],
        "collection_schema": [
            {
                "href": "https:\/\/example.com\/wp-json\/noptin\/v1\/subscribers\/collection_schema"
            }
        ]
    }
}

    Notes

    • All POST endpoints support batch operations.
    • All custom fields stored in Noptin can be used during subscriber filtering, creation, or update.
    • Use tags::add and tags::remove to manage tags incrementally.
    • The response format follows typical WP REST API conventions.

    Related Guides

    Leave a Reply

    Your email address will not be published. Required fields are marked *