API introduction

The Senderz public API is the API-key authenticated, server-to-server surface used by the Make connector, partner integrations and custom backends. It covers contact (profile) management, list membership, transactional email and SMS, delivery status, custom event ingest, one-time passcodes, embedded form submissions, outbound webhook subscriptions and reference lookups.

Base URL

https://api.senderz.app/api/v1

http://localhost:7010/api/v1

Every endpoint in this reference lives under the /api/v1 prefix. A small set of browser-facing assets and redirects is mounted at the domain root instead and is not part of the API:

Root path	Purpose
`GET /o.gif`	Email open tracking pixel.
`GET /c`	Tracked click redirect.
`GET /r/:slug`	SMS short link redirect.
`GET /storefront/senderz.js`	Storefront popup and tracking bundle.
`GET /storefront/push-sw.js`	Web push service worker.
`GET /forms/senderz-form.js`	Embedded form bundle.
`GET /.well-known/oauth-authorization-server`	OAuth discovery document for MCP clients.
`GET /.well-known/oauth-protected-resource`	OAuth discovery document for MCP clients.
`GET /.well-known/oauth-protected-resource/mcp`	OAuth discovery document for MCP clients.

Authentication

Every request carries two headers. There is no OAuth flow and no bearer token.

X-Sender-Tenant: acme-store
X-API-Key: sk_evt_...

X-Sender-Tenant accepts either your workspace slug or the workspace UUID. See Authentication for how to create, rotate and revoke keys, and for the exact failure responses.

Versioning

The current API version is 2026-01. It is returned as apiVersion by GET /public/me. There is no version header and no version segment in the path beyond /api/v1; new fields and endpoints are added compatibly.

The response envelope

Every successful response is wrapped in the same envelope. The shapes documented throughout this reference are the value of data.

{
  "success": true,
  "data": {
    "tenant": {
      "id": "9f1c2a44-4d0b-4f2e-9a6c-1b7d0e5a83c1",
      "slug": "acme-store",
      "name": "Acme Store",
      "plan": "c5000",
      "status": "active"
    },
    "apiVersion": "2026-01"
  }
}

Failures use success: false with a human-readable message. Some errors add a machine-readable code you can branch on:

{
  "success": false,
  "message": "Insufficient SMS credits",
  "code": "insufficient_credits"
}

Branch on code where it is present, and on the HTTP status otherwise. Never parse message, which is prose and can change.

Full status-code and error-shape detail lives in Errors and rate limits. List endpoints share one paging shape, documented in Pagination.

Making a request

string

Send application/json on any request with a body.

string

Optional. Up to 64 characters from A-Z, a-z, 0-9, _ and -. If you send a valid value it is used as the request id; otherwise one is generated. It is echoed back on the response as X-Request-Id on every request, valid or not. Log it and quote it to support.

Two request rules apply everywhere:

Request bodies are capped at 2 MB. A larger body is rejected before it reaches the handler.
Unknown properties are rejected. Bodies are whitelisted against the documented fields, so an unexpected or misspelled key returns 400 rather than being silently ignored.

Endpoint map

Ingest and transactional

Authenticated with the same header pair, but mounted outside /public.

Method and path	What it does	Reference
`POST /events/ingest`	Record a custom event, resolving or creating the profile and triggering automations.	Event ingest
`POST /otp/send`	Send a one-time passcode over SMS or voice.	OTP API
`POST /otp/verify`	Verify a passcode.	OTP API
`POST /forms/subscribe`	Submit an embedded form.	Forms API
`POST /push/subscriptions`	Register a browser web push subscription.	Push subscriptions

Public API

Method and path	What it does	Reference
`GET /public/me`	Validate the key and read workspace metadata.	Validate connection
`GET /public/profiles`	List profiles.	Profiles
`GET /public/profiles/lookup`	Find one profile by email or contact id.	Profiles
`GET /public/profiles/:id`	Get one profile by id.	Profiles
`POST /public/profiles`	Create a profile.	Profiles
`PUT /public/profiles`	Upsert a profile by email or phone.	Profiles
`PATCH /public/profiles`	Update a profile by email.	Profiles
`PATCH /public/profiles/:id`	Update a profile by id.	Profiles
`POST /public/profiles/blacklist`	Add an address or number to the suppression list.	Profiles
`DELETE /public/profiles/blacklist`	Remove a suppression entry.	Profiles
`GET /public/lists`	List the workspace lists.	Lists
`POST /public/lists/:id/members`	Add profiles to a list.	Lists
`DELETE /public/lists/:id/members`	Remove profiles from a list by email.	Lists
`DELETE /public/lists/:id/members/:contactId`	Remove one profile from a list by id.	Lists
`POST /public/messages/email`	Send a transactional email.	Messages
`POST /public/messages/sms`	Send a transactional SMS.	Messages
`GET /public/messages`	List message delivery statuses.	Messages
`GET /public/messages/:id`	Get one message delivery status.	Messages
`GET /public/webhooks`	List outbound webhook endpoints.	Webhooks
`POST /public/webhooks`	Subscribe an endpoint to events.	Webhooks
`DELETE /public/webhooks/:id`	Delete a subscription.	Webhooks

Reference lookups

Compact lists sized for populating dropdowns and validating input before a send.

Method and path	What it does	Reference
`GET /public/templates`	Templates, filterable by channel.	Resource dropdowns
`GET /public/templates/:id/merge-fields`	Merge fields a template expects.	Resource dropdowns
`GET /public/campaigns`	Campaigns.	Resource dropdowns
`GET /public/custom-fields`	Custom contact fields.	Resource dropdowns
`GET /public/sender-addresses`	Verified sender addresses for email sends.	Resource dropdowns
`GET /public/sms-sender-ids`	Approved SMS sender identities.	Resource dropdowns
`GET /public/tags`	Tags applied to campaigns, flows, templates and segments.	Tags
`POST /public/tags`	Create a tag.	Tags
`GET /public/events`	System and observed custom event names for webhook subscriptions.	Resource dropdowns

Where to start

Authentication

Create a key, set the two headers, and read the rate limits.

Validate connection

One call that proves the credentials work.

Profiles

Create, upsert, update, look up and suppress contacts.

Lists

Enumerate lists and manage membership.

Messages

Transactional email and SMS, plus delivery status.

Event ingest

Record custom events and trigger automations.

OTP API

Send and verify one-time passcodes.

Forms API

The subscribe endpoint behind embedded forms.

Webhooks

Subscribe to outbound events.

Resource dropdowns

Templates, campaigns, fields, senders and event names.

Push subscriptions

Rate limits

Two independent limits apply to every request. The tighter one is a shared 60 requests per minute bucket keyed on the caller source IP address, so it is shared with anything else calling from the same address. A second 1,200 requests per minute bucket is keyed on the API key itself. Both are documented in full, with the response headers and the throttled response body, in Authentication.

Introduction

Ingest & transactional

Public API

API introduction

Base URL

Authentication

Versioning

The response envelope

Making a request

Endpoint map

Ingest and transactional

Public API

Reference lookups

Where to start

Authentication

Validate connection

Profiles

Lists

Messages

Event ingest

OTP API

Forms API

Webhooks

Resource dropdowns

Tags

Push subscriptions

Rate limits

​Base URL

​Authentication

​Versioning

​The response envelope

​Making a request

​Endpoint map

​Ingest and transactional

​Public API

​Reference lookups

​Where to start

Authentication

Validate connection

Profiles

Lists

Messages

Event ingest

OTP API

Forms API

Webhooks

Resource dropdowns

Tags

Push subscriptions

​Rate limits

Base URL

Authentication

Versioning

The response envelope

Making a request

Endpoint map

Ingest and transactional

Public API

Reference lookups

Where to start

Rate limits