Resource dropdowns

These endpoints return compact option lists, sized for populating pickers in no-code tools like Make. Every item has a value (what you submit elsewhere in the API) and a label (what you show), plus a few extra keys per resource. All of them use the X-Sender-Tenant + X-API-Key headers. All except GET /public/templates/:id/merge-fields return the standard pagination envelope.

Every endpoint on this page binds a validated query object, so an unknown query parameter returns 400. Sending ?status=active to /public/sms-sender-ids or ?search=vip to /public/tags is a validation error, not an ignored filter. Only the parameters documented below are accepted.

Endpoints at a glance

Endpoint	Paged by	What `value` is
`GET /public/templates`	database	Template UUID
`GET /public/templates/:id/merge-fields`	not paged	n/a, returns a string array
`GET /public/campaigns`	database	Campaign UUID
`GET /public/custom-fields`	database	Custom field UUID
`GET /public/sender-addresses`	in memory	Sender email address
`GET /public/sms-sender-ids`	in memory	Sender ID string
`GET /public/tags`	in memory	Tag name
`POST /public/tags`	n/a	n/a, creates a tag
`GET /public/events`	in memory	Event key

“Paged in memory” means the full set is loaded, then limit and offset are applied to it. total is still the true count, and has_more and next_cursor behave exactly as on the database-paged endpoints. These sets are small by nature, so paging them is rarely necessary.

Templates

GET /api/v1/public/templates

integer

default:"50"

Page size. Range 1 to 100.

integer

default:"0"

Records to skip. Minimum 0.

string

Filter by channel. One of email, sms, push. Any other value returns 400.

Ordered by most recently updated first.

string

Template UUID. This is the id you pass as templateId elsewhere in the API.

string

Template name.

string

email, sms or push.

string[]

Merge tag keys found in this template, sorted and de-duplicated. Extracted from the subject line, the HTML body, the SMS body, the block document and the template metadata by scanning for {{key}} and {{key|fallback}}.

curl "https://api.senderz.app/api/v1/public/templates?channel=email&limit=25" \
  -H "X-Sender-Tenant: acme-store" \
  -H "X-API-Key: your-api-key"

{
  "success": true,
  "data": {
    "items": [
      {
        "value": "3f8a1c22-9d4e-4b17-8a0c-1e5f7b2d6a90",
        "label": "Welcome email",
        "channel": "email",
        "mergeFields": ["firstName", "storeName"]
      },
      {
        "value": "b1c7e504-2a6d-4f38-9c11-7d0e42a8b3f5",
        "label": "Order confirmation",
        "channel": "email",
        "mergeFields": ["firstName", "orderId"]
      }
    ],
    "limit": 25,
    "offset": 0,
    "total": 2,
    "has_more": false,
    "next_cursor": null
  }
}

This list is the workspace’s template library. Archived templates and templates created inside a campaign or automation are excluded, so a template a user can see in a campaign editor may not appear here. It is still readable by id.

Template merge fields

GET /api/v1/public/templates/{id}/merge-fields

string

required

Template UUID. A non-UUID value returns 400.

Takes no query parameters and returns a bare object, not the pagination envelope.

string[]

Merge tag keys, sorted and de-duplicated.

curl "https://api.senderz.app/api/v1/public/templates/3f8a1c22-9d4e-4b17-8a0c-1e5f7b2d6a90/merge-fields" \
  -H "X-Sender-Tenant: acme-store" \
  -H "X-API-Key: your-api-key"

{
  "success": true,
  "data": {
    "items": ["firstName", "orderId", "storeName"]
  }
}

This route reads the full rendered template, so it can return keys the list endpoint’s mergeFields misses, notably ones that live only in the push payload or in template settings. Use the list for a quick preview and this route when you need the authoritative set for one template.

Status	Cause
`400`	`id` is not a UUID.
`404`	No template with that id in this workspace.

Campaigns

GET /api/v1/public/campaigns

This endpoint binds the full campaign list query, so its paging defaults differ from the rest of the page.

integer

default:"25"

Page size. Range 1 to 200. Note this is not the 50/100 used by the other endpoints here.

integer

default:"1"

1-based page number. Minimum 1.

integer

Records to skip. Minimum 0. When present it wins over page. The response carries offset, never page.

string

Single status filter. One of draft, scheduled, sending, sent, paused, cancelled, failed.

string

Comma-separated list of the same statuses, for a multi-select. When present it replaces status.

string

One of email, sms. Campaigns have no push channel.

string

Case-insensitive substring match on the campaign name. Max 255 characters.

string

Sort key, max 64 characters. Sortable columns are createdAt, updatedAt, name, scheduleAt, sentAt. Prefix with - for descending (-createdAt), or use column:asc / column:desc. An unrecognised value falls back to updatedAt descending rather than erroring.

string

UUID. Only campaigns targeting that segment.

string

Comma-separated UUID list. Only campaigns carrying at least one of those tags.

boolean

default:"false"

true returns archived campaigns instead of live ones. Accepts true, false, 1, 0.

boolean

true returns only campaigns with more than one variant, false only single-variant campaigns. Omit for both.

string

Campaign UUID.

string

Campaign name.

string

email or sms.

string

draft, scheduled, sending, sent, paused, cancelled or failed.

curl "https://api.senderz.app/api/v1/public/campaigns?statuses=sent,sending&limit=50&sort=-sentAt" \
  -H "X-Sender-Tenant: acme-store" \
  -H "X-API-Key: your-api-key"

{
  "success": true,
  "data": {
    "items": [
      {
        "value": "7c2b9f10-53da-4e88-b6a1-9f0c4d2e8b73",
        "label": "Black Friday",
        "channel": "email",
        "status": "sent"
      },
      {
        "value": "1a4d6e93-8b02-4c57-9de1-5f3a7c0b2d46",
        "label": "Weekend SMS blast",
        "channel": "sms",
        "status": "sending"
      }
    ],
    "limit": 50,
    "offset": 0,
    "total": 2,
    "has_more": false,
    "next_cursor": null
  }
}

Because status is on every item, this endpoint doubles as a campaign-completion poll. Filter to a single campaign’s status window rather than relying on a campaign.sent webhook.

Custom fields

GET /api/v1/public/custom-fields

integer

default:"50"

Page size. Range 1 to 100.

integer

default:"0"

Records to skip. Minimum 0.

Ordered by most recently created first.

string

Custom field UUID.

string

The field’s human label, as set in the app.

string

The field’s stable key. This is what you write into a profile’s customProperties, not value.

string

Value type. One of text, number, date, boolean, select, multiSelect, url, list.

string[] | null

Allowed values for a select or multiSelect field. null for every other kind.

object[]

The same values pre-shaped as { label, value } for a select control. Always an array, empty when the field has no options.

curl "https://api.senderz.app/api/v1/public/custom-fields?limit=50" \
  -H "X-Sender-Tenant: acme-store" \
  -H "X-API-Key: your-api-key"

{
  "success": true,
  "data": {
    "items": [
      {
        "value": "d09a3b71-6c4e-4a25-8f13-2b7e5d0c9a48",
        "label": "T-shirt size",
        "key": "size",
        "kind": "select",
        "options": ["S", "M", "L"],
        "optionItems": [
          { "label": "S", "value": "S" },
          { "label": "M", "value": "M" },
          { "label": "L", "value": "L" }
        ]
      },
      {
        "value": "5e17c8a4-0d92-4b63-a7f5-8c1e94b6d203",
        "label": "Loyalty number",
        "key": "loyaltyNumber",
        "kind": "text",
        "options": null,
        "optionItems": []
      }
    ],
    "limit": 50,
    "offset": 0,
    "total": 2,
    "has_more": false,
    "next_cursor": null
  }
}

value is the field’s UUID and key is its property name. Writing a profile uses key. Sending the UUID as a property name creates a junk property instead of failing, so pick the right one.

Sender addresses

GET /api/v1/public/sender-addresses

The From addresses POST /public/messages/email will accept. The list is filtered to addresses whose domain is verified and whose inbox verification has completed, so anything returned here is safe to send from. A pending or failed inbox, or an address on an unverified domain, is omitted entirely.

integer

default:"50"

Page size. Range 1 to 100.

integer

default:"0"

Records to skip. Minimum 0.

string

The email address. Pass this as fromEmail.

string

Name <email> when the address has a From name set, otherwise just the address.

string | null

The configured From name, or null.

curl "https://api.senderz.app/api/v1/public/sender-addresses" \
  -H "X-Sender-Tenant: acme-store" \
  -H "X-API-Key: your-api-key"

{
  "success": true,
  "data": {
    "items": [
      {
        "value": "orders@acmestore.com",
        "label": "Acme Orders <orders@acmestore.com>",
        "fromName": "Acme Orders"
      },
      {
        "value": "hello@acmestore.com",
        "label": "hello@acmestore.com",
        "fromName": null
      }
    ],
    "limit": 50,
    "offset": 0,
    "total": 2,
    "has_more": false,
    "next_cursor": null
  }
}

An empty list means the workspace has no send-ready address yet. Domain and inbox verification happen in the Senderz app; neither is part of this API.

SMS sender IDs

GET /api/v1/public/sms-sender-ids

The branded sender IDs POST /public/messages/sms and POST /otp/send will accept. Only approved and active sender IDs are returned. A pending or rejected request is omitted, so an id you can see in the app may not appear here yet.

integer

default:"50"

Page size. Range 1 to 100.

integer

default:"0"

Records to skip. Minimum 0.

string

The sender ID string. Pass this as senderId.

string

Same as value.

curl "https://api.senderz.app/api/v1/public/sms-sender-ids" \
  -H "X-Sender-Tenant: acme-store" \
  -H "X-API-Key: your-api-key"

{
  "success": true,
  "data": {
    "items": [
      { "value": "ACMESTORE", "label": "ACMESTORE" }
    ],
    "limit": 50,
    "offset": 0,
    "total": 1,
    "has_more": false,
    "next_cursor": null
  }
}

Requesting a new sender ID is done in the Senderz app; approval is not part of this API.

Create a tag

POST /api/v1/public/tags

The one write on this page. It creates a tag in the workspace resolved from your API key.

string

required

Tag name. Non-empty, max 60 characters. Leading and trailing whitespace is trimmed before the uniqueness check.

string

One of neutral, primary, accent, warn, danger, info, violet. Omit for no colour. Any other value returns 400.

Returns 201 with the created tag.

string

Tag UUID.

string

The trimmed name.

string | null

The colour, or null.

string

ISO 8601 timestamp.

string

ISO 8601 timestamp.

curl -X POST "https://api.senderz.app/api/v1/public/tags" \
  -H "X-Sender-Tenant: acme-store" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "vip", "color": "primary" }'

const res = await fetch("https://api.senderz.app/api/v1/public/tags", {
  method: "POST",
  headers: {
    "X-Sender-Tenant": process.env.SENDERZ_WORKSPACE,
    "X-API-Key": process.env.SENDERZ_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "vip", color: "primary" }),
});

// A tag that already exists is a 409, not a silent success.
if (res.status === 409) { /* reuse the existing tag */ }

{
  "success": true,
  "data": {
    "id": "a3f0c519-7b28-4d6e-91a4-0c85b2e7f631",
    "name": "vip",
    "color": "primary",
    "createdAt": "2026-08-14T09:12:44.108Z",
    "updatedAt": "2026-08-14T09:12:44.108Z"
  }
}

Status	`code`	Cause
`400`		`name` is missing or empty, over 60 characters, or `color` is not an allowed value.
`400`	`tag_limit_reached`	The workspace already has 200 tags, the per-workspace maximum.
`409`	`tag_name_taken`	A tag with that name already exists in this workspace.

409

{
  "success": false,
  "message": "A tag with that name already exists",
  "code": "tag_name_taken"
}

Creating a tag is not idempotent. If you are syncing tags from another system, treat 409 tag_name_taken as success and read the existing tag from GET /public/tags.

Events

GET /api/v1/public/events

The event vocabulary for this workspace: the system events you can subscribe a webhook to, followed by the custom events this workspace has actually recorded through event ingest. System events come first, in a fixed order; custom events follow.

integer

default:"50"

Page size. Range 1 to 100. The full catalog is larger than the default page, so raise this or page through it.

integer

default:"0"

Records to skip. Minimum 0.

string

The event key. For a system event this is the value you pass in a webhook subscription’s events array. For a custom event it is the event name you send to event ingest.

string

Display name. Equal to value for a system event; the workspace’s own display name for a custom event.

string

system for a built-in webhook event, custom_event for one observed in this workspace.

object[]

Present on custom events only. The properties seen or declared on that event, so a picker can offer them without a second call.

Show properties[]

string

Stable property key.

string

Display name.

string

One of string, number, boolean, datetime, list, object.

string

declared when configured in the app, observed when inferred from recorded events.

boolean

true when this property carries the event’s numeric value.

string | null

ISO 8601 timestamp of the last event carrying this property, or null.

curl "https://api.senderz.app/api/v1/public/events?limit=100" \
  -H "X-Sender-Tenant: acme-store" \
  -H "X-API-Key: your-api-key"

{
  "success": true,
  "data": {
    "items": [
      { "value": "order.completed", "label": "order.completed", "kind": "system" },
      { "value": "order.refunded", "label": "order.refunded", "kind": "system" },
      { "value": "order.fulfilled", "label": "order.fulfilled", "kind": "system" },
      {
        "value": "quiz_completed",
        "label": "Quiz completed",
        "kind": "custom_event",
        "properties": [
          {
            "key": "score",
            "label": "Score",
            "dataType": "number",
            "provenance": "observed",
            "isValueProperty": false,
            "lastSeenAt": "2026-08-21T17:04:02.551Z"
          }
        ]
      }
    ],
    "limit": 100,
    "offset": 0,
    "total": 30,
    "has_more": false,
    "next_cursor": null
  }
}

Only active custom events are listed. A custom event that has been retired in the app disappears from this list even though its historical data remains. A system event is always listed whether or not this workspace has ever produced one.

Send a message

Where fromEmail and senderId from this page are used.

Webhooks

Subscribe to the system events listed above.

Pagination

The limit, offset, has_more and next_cursor contract.

Errors

Status codes, the error envelope and rate limits.

Introduction

Ingest & transactional

Public API

Resource dropdowns

Endpoints at a glance

Templates

Template merge fields

Campaigns

Custom fields

Sender addresses

SMS sender IDs

Tags

Create a tag

Events

Send a message

Webhooks

Pagination

Errors

​Endpoints at a glance

​Templates

​Template merge fields

​Campaigns

​Custom fields

​Sender addresses

​SMS sender IDs

​Tags

​Create a tag

​Events

Send a message

Webhooks

Pagination

Errors

Endpoints at a glance

Templates

Template merge fields

Campaigns

Custom fields

Sender addresses

SMS sender IDs

Tags

Create a tag

Events