Overview

Base URL

https://api.paubox.com/v1/marketing

Authorization

Include an Authorization header with every request: Authorization: Token token=YOUR_API_KEY Replace YOUR_API_KEY with your API key. Generate your key on the Paubox Marketing > Settings page (note: each API key is displayed only once upon creation):

Example call

curl -X POST \
  https://api.paubox.com/v1/marketing/subscribers \
  -H 'Authorization: Token token=YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "subscriber": {
      "email": "recipient@example.com",
      "first_name": "Jane",
      "last_name": "Smith"
    }
  }'

Core concepts

Four resources cover most of what the Marketing API does. Understanding how they relate makes the rest of the reference easier to navigate.

Resource	What it is
Campaign mailing	The email itself — subject, HTML body, text body. Creating one only stores content; it sends nothing.
Subscriber	A person in your account, identified by email address.
List	Who receives a campaign. Either a subscription list (explicit membership) or a dynamic list (membership computed from saved filters).
Subscription	The link between one subscriber and one list. This is where a list-level opt-out is recorded.

A send ties them together: it takes one campaign mailing, one list (or an explicit set of recipient addresses), and delivers the mailing to that audience. The same mailing can be sent more than once, and each send is tracked separately in analytics.

Subscription lists vs. dynamic lists:Membership in a subscription list is explicit — you add and remove subscribers yourself. Membership in a dynamic list is derived from filters saved on the list, so it changes as your subscriber data changes. Endpoints that act on a list in bulk come in two variants for this reason: bulk_global_* for subscription lists, dynamic_bulk_* for dynamic lists.

Send a campaign

Create the campaign mailing

Create a campaign with your subject and content. subject is required and must be unique within your account.

curl -X POST \
  https://api.paubox.com/v1/marketing/campaign_mailings \
  -H 'Authorization: Token token=YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "campaign_mailing": {
      "subject": "March newsletter",
      "html_part": "<html><body><div>Hello</div></body></html>",
      "text_part": "Hello",
      "template_type": "html"
    }
  }'

The response contains the new mailing’s ID, which you will need for every step that follows:

{ "data": { "id": "123e4567-e89b-12d3-a456-426614174000" } }

An unsubscribe footer is appended to html_part automatically, so you do not need to add one yourself.

Preview it

Send a test email to a single address to check rendering before you send to a list. The subject is prefixed with [Test], and test sends are not recorded in analytics.

curl -X GET \
  'https://api.paubox.com/v1/marketing/campaign_mailings/123e4567-e89b-12d3-a456-426614174000/send_test_email?to_email=me@example.com' \
  -H 'Authorization: Token token=YOUR_API_KEY'

A successful test send returns 204 No Content with an empty body.

Revise if needed

Update the campaign to change any field. Only the fields you send are modified.

Send or schedule

Send the campaign to go out now, or schedule it for a future time. Both take the campaign mailing ID plus a target — a subscription_list_id, a dynamic_list_id, or an explicit list of recipient_emails.

Sending is asynchronous.A successful response means the send was accepted and queued, not that delivery has finished. Track progress through the campaign analytics endpoints rather than the send response.

Measure

Use the analytics endpoints to see how the campaign performed: send totals, per-send results, individual deliveries, and tracking link engagement.

Tip:A brand-new Paubox Marketing account may be temporarily prevented from scheduling its first campaign as an anti-abuse measure. If you hit a 403 with a message about new accounts, contact support@paubox.com and they can clear it for you.

Manage opt-ins and opt-outs

Paubox Marketing records two independent levels of opt-out, and it matters which one you use.

Level	Where it lives	Effect
List-level	`unsubscribed_at` on the subscription	The subscriber stops receiving campaigns sent to that one list. They still receive campaigns sent to other lists.
Global	`opted_out_on` on the subscriber	The subscriber receives nothing, across every list.

Which one an endpoint applies depends on whether you send subscription_list_ids:

POST /subscriptions/unsubscribe with subscription_list_ids records a list-level opt-out.
The same endpoint without subscription_list_ids records a global opt-out.
POST /subscriptions/subscribe always clears the global opt-out, because a subscriber who is subscribed to any list is by definition not globally unsubscribed.

Treat a global opt-out as permanent unless the recipient asks to be resubscribed. Re-subscribing someone who opted out, without a new request from them, is exactly the pattern that damages sending reputation and can put you out of compliance with anti-spam rules.

For a single subscriber and list you already have a subscription record for, deleting the subscription is the most direct route — it stamps unsubscribed_at and leaves everything else untouched.

Acting on a whole list

When you want to opt out an entire list rather than a known set of subscribers, use the bulk endpoints. They accept a from_subscription_list_id and operate on everyone in that list, minus any except_ids you supply — useful for “select all except these” flows.

Subscription lists: bulk global subscribe and bulk global unsubscribe
Dynamic lists: bulk subscribe and bulk unsubscribe

These endpoints run in the background. See Background jobs below.

API conventions

Identifiers

Records are identified by UUID. A campaign_mailing_id, subscription_list_id, or subscriber ID in a URL or request body is always the UUID form:

123e4567-e89b-12d3-a456-426614174000

See Locating parameter values for where to find each one in the dashboard.

One exception:POST /subscriptions takes the subscriber’s internal numeric ID rather than the UUID. To add a subscriber to a list using the UUID you already have, create the subscriber with a subscription_list_id instead, or use POST /subscriptions/subscribe.

Response shapes

Most read endpoints return resources in JSON:API form — an id, a type, and the fields nested under attributes:

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "campaign_mailing",
    "attributes": {
      "subject": "March newsletter",
      "created_at": "2026-03-01T12:00:00Z"
    }
  }
}

Write endpoints are terser. Creating or updating a campaign mailing returns only the ID, not the full record:

{ "data": { "id": "123e4567-e89b-12d3-a456-426614174000" } }

List and detail responses for the same resource do not always carry the same fields. Listing campaign mailings includes aggregate counts (sent_count, delivered_count, and so on) but omits the content; fetching a single one includes html_part, text_part, and form_data but omits the counts. Each reference page documents its own response.

Errors

Check the response body, not just the status code.Several Marketing API write endpoints return 200 OK when a request fails validation, with the problem reported in an errors key instead of data. A client that branches only on HTTP status will treat these as successes.

A failed write looks like this:

{ "errors": ["Subject has already been taken"] }

Endpoints that behave this way include creating and updating a campaign mailing, creating a subscription, and the subscribe and unsubscribe endpoints. Treat the presence of errors as the failure signal, and fall back to the status code for authentication (401), missing records (404), and server errors (500).

Pagination

List endpoints are paginated by default. Control it with:

Parameter	Purpose
`items`	Records per page
`page`	Which page to return
`pagination`	Set to `false` to disable paging and return everything in one response

Pagination metadata is returned in the response headers. Some endpoints additionally include a page_info object in the response body.

Background jobs

Operations that can affect a large number of records do not run inline. Instead they queue a job and return its identifier immediately:

{ "data": { "jid": "a1b2c3d4e5f6a7b8c9d0e1f2" } }

A jid in the response means the work was accepted, not that it has finished. Bulk subscribe and unsubscribe across a whole list behave this way; supplying an explicit subscriber_ids array to those same endpoints processes the change inline and returns the affected subscribers instead.

Dates

Dates are passed as ISO8601 strings with UTC timezone.

Finding id parameters for subscription_list_id, campaign_mailing_id, etc.

Finding parameter values in the web dashboard

Community & support

Q&A

Ask usage questions in the Paubox Community.

Ideas

Propose features and improvements.

Never post PHI, recipient addresses, or message content in public threads. Account, billing, or anything sensitive goes to support@paubox.com.

Get started

Email API

Migrate to Paubox

Marketing API

MCP Server

SDKs

CLI

Forms API

Base URL

Authorization

Example call

Core concepts

Send a campaign

Manage opt-ins and opt-outs

Acting on a whole list

API conventions

Identifiers

Response shapes

Errors

Background jobs

Dates

Finding id parameters for subscription_list_id, campaign_mailing_id, etc.

Finding parameter values in the web dashboard

Community & support

Q&A

Ideas

​Base URL

​Authorization

​Example call

​Core concepts

​Send a campaign

​Manage opt-ins and opt-outs

​Acting on a whole list

​API conventions

​Identifiers

​Response shapes

​Errors

​Pagination

​Background jobs

​Dates

​Finding id parameters for subscription_list_id, campaign_mailing_id, etc.

Finding parameter values in the web dashboard

​Community & support

Q&A

Ideas

Base URL

Authorization

Example call

Core concepts

Send a campaign

Manage opt-ins and opt-outs

Acting on a whole list

API conventions

Identifiers

Response shapes

Errors

Pagination

Background jobs

Dates

Finding id parameters for subscription_list_id, campaign_mailing_id, etc.

Community & support