> For the complete documentation index, see [llms.txt](https://userguide.zappost.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://userguide.zappost.com/zap-api/api-endpoints/campaigns.md).

# Campaigns

Campaigns allow users to send direct mail based on a real time events or actions which is specific to an individual customer.\
Each campaign has it's own configuration of required data in order to trigger a relevant ZAP for example a an abandoned basket campaign might require a session ID and a list of products but a customer birthday might only expect the recipient info and a birthday date

Users can list all campaigns available in ZAP POST. This will provide some basic campaign information such as the name and current status.&#x20;

## GET /api/v1/campaigns

>

```json
{"openapi":"3.0.1","info":{"title":"ZAPI","version":"1.0.0"},"security":[{"Basic":[]}],"components":{"securitySchemes":{"Basic":{"type":"http","scheme":"basic"}},"schemas":{"CampaignDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clientId":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date-time","nullable":true},"duration":{"type":"integer","format":"int32","nullable":true},"zapLimit":{"type":"integer","format":"int32","nullable":true},"csvPath":{"type":"string","nullable":true},"enabled":{"type":"boolean","nullable":true},"status":{"type":"string","nullable":true},"paperStockId":{"type":"string","format":"uuid","nullable":true},"zapsSent":{"type":"integer","format":"int32","nullable":true},"archivedDate":{"type":"string","format":"date-time","nullable":true},"templateId":{"type":"string","format":"uuid","nullable":true},"sampleDataCsvBlobUrl":{"type":"string","nullable":true}},"additionalProperties":false}}},"paths":{"/api/v1/campaigns":{"get":{"tags":["Campaigns"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CampaignDto"}}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"500":{"description":"Server Error"}}}}}}
```

Users can also look up a specific campaign which will include more detailed information regarding the custom field configuration on the campaign such as [expected values](#expected-values) and [validation expressions](#validation-expressions).&#x20;

## GET /api/v1/campaign/{campaignId}

>

```json
{"openapi":"3.0.1","info":{"title":"ZAPI","version":"1.0.0"},"security":[{"Basic":[]}],"components":{"securitySchemes":{"Basic":{"type":"http","scheme":"basic"}},"schemas":{"CampaignRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","nullable":true},"paperStockName":{"type":"string","nullable":true},"paperStockId":{"type":"string","nullable":true},"frontPublishedDesign":{"type":"string","nullable":true},"backPublishedDesign":{"type":"string","nullable":true},"fields":{"type":"array","items":{"$ref":"#/components/schemas/CampaignDetailsField"},"nullable":true}},"additionalProperties":false},"CampaignDetailsField":{"type":"object","properties":{"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"exampleValue":{"type":"string","nullable":true},"mandatory":{"type":"boolean"},"expectedValues":{"type":"array","items":{"type":"string"},"nullable":true},"validationExpressions":{"type":"array","items":{"$ref":"#/components/schemas/ValidationExpressionRequest"},"nullable":true}},"additionalProperties":false},"ValidationExpressionRequest":{"type":"object","properties":{"expression":{"type":"string","nullable":true},"message":{"type":"string","nullable":true}},"additionalProperties":false}}},"paths":{"/api/v1/campaign/{campaignId}":{"get":{"tags":["Campaigns"],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignRequest"}}}},"401":{"description":"Unauthorized"}}}}}}
```

### Useful Information

#### Campaign IDs are required for Submissions

Most of the time you'll be listing campaigns to find the ID of the appropriate campaign you wish to create a submission against or to check the progress of a historically created submission.&#x20;

#### Expected Values

Expected values are configured against fields on the campaign. If any expected values exist, then the API will only accept the values within that list. \
For example, I might configure a DayOfTheWeek field on my campaign. If I do this I may configure the expected values "Monday","Tuesday","Wednesday","Thursday","Friday","Saturday" and "Sunday". \
This is intended to provide some basic validation to clients configuring their campaigns.

#### Validation Expressions

Validations are regex expressions and paired messages. When a record is received against the campaign ZAP will validate that all validation expressions are passed. If any fail, a list of errors will be compiled with the relevant message configured for the validation expression. \
This piece of functionality provides more advanced validation as the regex expressions can get quite complex.&#x20;


---

# 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://userguide.zappost.com/zap-api/api-endpoints/campaigns.md?ask=<question>&goal=<user_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.
