Your API key

Create one in the portal under API keys.

Browse the API

API reference

Campaigns

Dated banners appended under signatures, for promotions and notices.

4 endpoints

GET/api/v1/campaigns

List campaigns

Every banner campaign, newest first.

campaigns:read

This endpoint takes no parameters beyond the URL itself.

Example response

json

{
  "campaigns": [
    {
      "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a80",
      "name": "Autumn promotion",
      "html_content_b": null,
      "winner": null,
      "audience": "external",
      "new_only": false,
      "start_date": "2026-10-01T00:00:00.000Z",
      "end_date": "2026-10-31T23:59:59.000Z",
      "target_scope": "all",
      "target_value": null,
      "target_name": null,
      "active": true
    }
  ],
  "total": 1
}

Copy and paste

curl -X GET "https://api.usesigned.co.uk/api/v1/campaigns" \
  -H "X-API-Key: $SIGNED_API_KEY"

POST/api/v1/campaigns

Create a campaign

Adds a banner under signatures between two dates. Outside those dates it is ignored, so you can set one up in advance.

campaigns:writeplan feature: campaigns

Parameters

JSON body

nameRequired
stringCampaign name, for your reference.
up to 255 characters
example: "Autumn promotion"
html_contentRequired
stringBanner HTML.
example: "<a href=\"https://acme.com/autumn\">Book a call this October</a>"
html_content_bOptional
stringA second version to A/B test against the first. Each email gets one at random until a winner is set. Pro plan.
audienceOptional
one ofShow the banner on every email, only when someone outside the organisation is on it, or only internal ones.
one of: all, external, internal · default "all"
new_onlyOptional
booleanLeave the banner off replies and forwards.
default false
start_dateOptional
dateFirst day the banner shows, as YYYY-MM-DD.
YYYY-MM-DD
example: "2026-10-01"
end_dateOptional
dateLast day the banner shows, as YYYY-MM-DD. The banner runs to the end of that day.
YYYY-MM-DD
example: "2026-10-31"
target_scopeOptional
one ofEveryone, or one department.
one of: all, department · default "all"
target_valueOptional
stringDepartment ID when target_scope is department.
uuid
activeOptional
booleanSwitch the campaign off without deleting it.
default true

Example request body

json

{
  "name": "Autumn promotion",
  "html_content": "<a href=\"https://acme.com/autumn\">Book a call this October</a>",
  "start_date": "2026-10-01",
  "end_date": "2026-10-31",
  "target_scope": "all"
}

Example response

json

{
  "campaign": {
    "id": "e5f6a7b8-c9d0-4f1f-8a2b-3c4d5e6f7a80",
    "name": "Autumn promotion",
    "active": true
  }
}

Copy and paste

curl -X POST "https://api.usesigned.co.uk/api/v1/campaigns" \
  -H "X-API-Key: $SIGNED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Autumn promotion","html_content": "<a href=\"https://acme.com/autumn\">Book a call this October</a>","start_date": "2026-10-01","end_date": "2026-10-31","target_scope": "all"}'

PATCH/api/v1/campaigns/{id}

Update a campaign

Updates a campaign. Send only the fields you want to change.

campaigns:writeplan feature: campaigns

Parameters

In the path

idRequired
stringCampaign ID.
uuid

JSON body

nameOptional
stringCampaign name.
up to 255 characters
html_contentOptional
stringBanner HTML.
html_content_bOptional
stringVersion B for an A/B test. Send null to stop testing. Pro plan.
winnerOptional
one ofPick the version everyone gets from now on, ending the test. Cleared when version B changes.
one of: a, b
audienceOptional
one ofEvery email, external only or internal only.
one of: all, external, internal
new_onlyOptional
booleanLeave the banner off replies and forwards.
start_dateOptional
dateFirst day the banner shows, as YYYY-MM-DD.
YYYY-MM-DD
end_dateOptional
dateLast day the banner shows, as YYYY-MM-DD.
YYYY-MM-DD
target_scopeOptional
one ofEveryone, or one department.
one of: all, department
target_valueOptional
stringDepartment ID when target_scope is department.
uuid
activeOptional
booleanSwitch the campaign off without deleting it.

Example request body

json

{
  "end_date": "2026-11-14"
}

Example response

json

{
  "campaign": {
    "id": "e5f6a7b8-c9d0-4f1f-8a2b-3c4d5e6f7a80",
    "end_date": "2026-11-14T23:59:59.000Z"
  }
}

Copy and paste

curl -X PATCH "https://api.usesigned.co.uk/api/v1/campaigns/{id}" \
  -H "X-API-Key: $SIGNED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"end_date": "2026-11-14"}'

DELETE/api/v1/campaigns/{id}

Delete a campaign

Deletes a campaign. Set active to false instead if you may want it again.

campaigns:write

Parameters

In the path

idRequired
stringCampaign ID.
uuid

Example response

json

{
  "deleted": true
}

Copy and paste

curl -X DELETE "https://api.usesigned.co.uk/api/v1/campaigns/{id}" \
  -H "X-API-Key: $SIGNED_API_KEY"