> For the complete documentation index, see [llms.txt](https://docs.parcellab.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parcellab.com/docs/developers/campaign-manager/campaigns.md).
# Campaigns
Our API allows you to retrieve targeted campaign data and collect analytics data for your campaigns.
## Overview
These requests allow you to get campaign data based on targeting parameters and gain insights into your campaign performance with a single HTTPS request.
You can retrieve active campaigns through these APIs using set parameters (for example: language and campaign medium) in order to find matching campaigns for evaluation. Additionally, you can track campaign event data for analytics purposes and monitor how your campaigns are performing.
## Get Campaign Data
You can retrieve campaign data of active campaigns based on the parameters provided using the `v4/campaign/evaluate` endpoint.
## Evaluate Campaign Targeting
> Evaluates active campaigns for given targeting parameters and returns campaign data, if there\
> is a matching campaign.
```json
{"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"paths":{"/v4/campaign/evaluate/":{"get":{"operationId":"campaign_evaluate_retrieve","description":"Evaluates active campaigns for given targeting parameters and returns campaign data, if there\nis a matching campaign.","summary":"Evaluate Campaign Targeting","parameters":[{"in":"query","name":"accountId","schema":{"type":"integer"}},{"in":"query","name":"campaignId","schema":{"type":"string","minLength":1,"maxLength":24}},{"in":"query","name":"language","schema":{"type":"string","minLength":1,"maxLength":5}},{"in":"query","name":"medium","schema":{"enum":["email","web","returns"],"type":"string","minLength":1},"description":"* `email` - Email\n* `web` - Web\n* `returns` - Returns Portal"},{"in":"query","name":"message","schema":{"type":"string","minLength":1,"maxLength":255}},{"in":"query","name":"orderNumber","schema":{"type":"string","minLength":1}},{"in":"query","name":"preview","schema":{"type":"boolean"}},{"in":"query","name":"status","schema":{"type":"string","minLength":1,"maxLength":255}},{"in":"query","name":"trackingId","schema":{"type":"string"},"description":"24-char hex MongoDB ObjectId of the tracking document"}],"tags":["Campaign"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBlocksResponse"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}},"components":{"schemas":{"ContentBlocksResponse":{"type":"object","properties":{"campaignId":{"type":["string","null"],"maxLength":24},"trackingId":{"type":["string","null"],"maxLength":24},"customerSegmentationId":{"type":["string","null"],"maxLength":24},"audienceId":{"type":["string","null"],"maxLength":24},"openTrackingUrl":{"type":"string","maxLength":1024},"analyticsBaseUrl":{"type":"string","maxLength":1024},"values":{"type":"object","additionalProperties":{}},"placeholders":{"type":"object","additionalProperties":{}},"typedValues":{"type":"object","additionalProperties":{}},"accountHasActiveCampaigns":{"type":["boolean","null"]}},"required":["accountHasActiveCampaigns","campaignId","placeholders","trackingId","values"]},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}}}
```
## Collect Campaign Events
Use `GET /v4/campaign/redirect/` to record an event and optionally redirect the visitor. This endpoint collects analytics events; it does not return an analytics report.
## Campaign Analytics Service
> Collects campaign event data (clicks & opens) for analytics purposes and forwards the\
> user to the redirect URL if provided.
```json
{"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"paths":{"/v4/campaign/redirect/":{"get":{"operationId":"campaign_redirect_retrieve","description":"Collects campaign event data (clicks & opens) for analytics purposes and forwards the\nuser to the redirect URL if provided.","summary":"Campaign Analytics Service","parameters":[{"in":"query","name":"c","schema":{"type":"string","minLength":1,"maxLength":24}},{"in":"query","name":"campaignId","schema":{"type":"string","minLength":1,"maxLength":24}},{"in":"query","name":"contentType","schema":{"type":"string","minLength":1,"maxLength":1024}},{"in":"query","name":"customerSegmentationId","schema":{"type":"string","minLength":1,"maxLength":24}},{"in":"query","name":"e","schema":{"type":"string"},"description":"24-char hex MongoDB ObjectId of the email document"},{"in":"query","name":"emailId","schema":{"type":"string"},"description":"24-char hex MongoDB ObjectId of the email document"},{"in":"query","name":"eventType","schema":{"enum":["open","click"],"type":"string","minLength":1},"description":"* `open` - open\n* `click` - click","required":true},{"in":"query","name":"medium","schema":{"enum":["email","web","returns"],"type":"string","minLength":1},"description":"* `email` - Email\n* `web` - Web\n* `returns` - Returns Portal"},{"in":"query","name":"redirectUrl","schema":{"type":"string","minLength":1,"maxLength":1024}},{"in":"query","name":"s","schema":{"type":"string","minLength":1,"maxLength":24}},{"in":"query","name":"trackingId","schema":{"type":"string"},"description":"24-char hex MongoDB ObjectId of the tracking document"}],"tags":["Campaign"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentBlocksResponse"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}},"components":{"schemas":{"ContentBlocksResponse":{"type":"object","properties":{"campaignId":{"type":["string","null"],"maxLength":24},"trackingId":{"type":["string","null"],"maxLength":24},"customerSegmentationId":{"type":["string","null"],"maxLength":24},"audienceId":{"type":["string","null"],"maxLength":24},"openTrackingUrl":{"type":"string","maxLength":1024},"analyticsBaseUrl":{"type":"string","maxLength":1024},"values":{"type":"object","additionalProperties":{}},"placeholders":{"type":"object","additionalProperties":{}},"typedValues":{"type":"object","additionalProperties":{}},"accountHasActiveCampaigns":{"type":["boolean","null"]}},"required":["accountHasActiveCampaigns","campaignId","placeholders","trackingId","values"]},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}}}
```
### Use the Returned Tracking URLs
The evaluation response includes `openTrackingUrl` and `analyticsBaseUrl` when a campaign is available. Use these URLs as returned. They contain campaign and tracking context and can use a different host and route version from the evaluation request.
* Use `openTrackingUrl` as the image URL for the campaign’s open-tracking pixel. Outside email, add `medium=web` or `medium=returns`; without `medium`, the open is recorded as `email`.
* Use `analyticsBaseUrl` as the base for click links. Preserve its existing query parameters, then add `eventType=click`, the `medium` (`email`, `web`, or `returns`), and the URL-encoded `redirectUrl`.
* For a product-recommendation click, add `rec=1`. For an ordinary campaign click, omit `rec`. Do not use `rec=false`: a nonempty value is treated as a recommendation click.
* Product-recommendation `article_url` values in the evaluation response are already click-tracking links. Use them as returned.
The following example assumes `campaign` contains the evaluation response:
```javascript
const clickUrl = new URL(campaign.analyticsBaseUrl);
clickUrl.searchParams.set('eventType', 'click');
clickUrl.searchParams.set('medium', 'web');
clickUrl.searchParams.set('redirectUrl', 'https://shop.example.com/products/shirt');
// Include only for a product-recommendation link.
clickUrl.searchParams.set('rec', '1');
const href = clickUrl.toString();
```
Use a destination approved for your campaign. A permitted `redirectUrl` produces an HTTP `302` redirect. Without it, the endpoint returns HTTP `200` with an empty body. An event is recorded only when both `eventType` and `medium` are present. An invalid or blocked destination can return `400`. A successful redirect confirms navigation; it does not by itself confirm that an analytics event was stored.
`GET /v4/campaign/evaluate/` and `GET /v4/campaign/redirect/` are public endpoints and do not require an API token. The returned tracking URLs also work without a token. The generated OpenAPI reference currently shows an incorrect token requirement for these endpoints; see [Access by Endpoint](/docs/developers/getting-started/authentication.md#access-by-endpoint).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.parcellab.com/docs/developers/campaign-manager/campaigns.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.