SendPromptly API Overview: Endpoints & Usage

SendPromptly is an event ingestion API for transactional notifications. Your application sends one event, and SendPromptly handles template lookup, delivery run creation, retries, and tracking for email and webhook channels.

Base URL

1
https://app.sendpromptly.com/api

Core endpoint

1
POST /v1/events

Required headers

Authorization: Bearer sp_{env}_{token}
Idempotency-Key: <unique-key>
Content-Type: application/json

Use environment-scoped tokens so your dev, stage, and prod traffic stay isolated.

Request contract

Field	Type	Required	Notes
`event_key`	string	Yes	Stable business event name, for example `order.created`.
`recipient`	object	Yes	Target identity for template rendering and delivery.
`payload`	object	Yes	Event-specific context used by templates.
`schedule_at`	datetime	No	Optional delayed execution time for scheduled notifications.

Design your event_key values around domain actions rather than UI actions. Stable keys reduce template churn and make analytics cleaner.

Idempotency and retries

SendPromptly enforces idempotency for ingestion requests, helping you safely retry after network failures or 5xx responses without accidental duplicate deliveries. Use a deterministic idempotency key derived from your business event id.

Delivery lifecycle

After acceptance, SendPromptly validates the event, resolves active templates, and creates delivery runs per enabled channel. Each run is tracked with status and timing metadata in the dashboard for debugging and operations.

Quick request example

1
2
3
4
5
6
7
8
9
curl -X POST https://app.sendpromptly.com/api/v1/events \
  -H "Authorization: Bearer sp_prod_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: order-100023-created" \
  -H "Content-Type: application/json" \
  -d '{
    "event_key": "order.created",
    "recipient": {"email": "customer@example.com", "name": "A. Customer"},
    "payload": {"order_id": "O-100023", "total": 125.50, "currency": "USD"}
  }'