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. Creating and changing them needs the Pro plan.

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. Pro plan.

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://www.domain.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://www.domain.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://www.domain.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. Pro plan.

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"