canonical: https://jentic.com/apis/api.engagespot.co/engagespot # Engagespot API Jentic publishes the only available OpenAPI specification for Engagespot API, keeping it validated and agent-ready. Engagespot is a multi-channel notification infrastructure that lets product teams send in-app, email, SMS, push, web push, and Slack notifications from a single API. Workflows handle channel routing, batching, digesting, and per-user preferences so engineers do not have to build delivery logic per channel. The 8-endpoint REST API covers triggering notifications, managing recipient users, reading and updating user preferences, and cancelling in-flight workflow runs. ## For AI agents Send multi-channel notifications (in-app, email, SMS, push, Slack), manage notification recipients, and read or update user notification preferences for product workflows. ## Scope Does not handle email template authoring, raw SMTP delivery, or marketing campaign automation - use for transactional multi-channel notification dispatch and recipient preference management only. ## Capabilities - Trigger a notification workflow that fans out to in-app, email, SMS, push, and Slack channels - Create or upsert a recipient user record with channel identifiers like email and phone - Cancel an in-flight workflow run before it dispatches to recipients - Read a user's notification preferences across channels and categories - Bulk delete notifications from a user's inbox - Look up the delivery status and history of a sent notification ## Use cases ### Multi-Channel Transactional Notifications Trigger a single workflow that delivers the same event (password reset, order confirmation, payment receipt) across in-app inbox, email, SMS, push, and Slack without writing channel-specific delivery code. Engagespot routes per recipient based on channel availability and user preferences. Typical setup is under a day once a workflow template is defined in the Engagespot dashboard. Example prompt: POST /notifications with workflow identifier 'order-shipped' and recipient userId 'cust_4821' to fan out a shipment notification across email and in-app channels ### User Preference Management Expose a notification preferences UI in your product where users opt in or out of categories per channel. The Engagespot API reads and updates these preferences so the workflow engine respects user choice automatically on every send. Reduces unsubscribe rates and meets compliance requirements for marketing communications. Example prompt: GET /preferences for userId 'usr_9920' to fetch the user's category-by-channel preference matrix and present it for editing ### User Lifecycle Sync Keep Engagespot's recipient directory in sync with your application's user records. Create users on signup with their email, phone, and timezone, and delete them on account closure to honour data deletion requests. The /users endpoint supports both create and delete in the same workflow. Example prompt: POST /users to register a new recipient with userId 'cust_4821', email and phone, then later DELETE /users when the customer closes their account ### AI Agent Notification Dispatch via Jentic An AI agent that monitors a process (build pipeline, fraud signal, support ticket SLA) can call the Engagespot API through Jentic to alert the right humans across the channels they prefer. Jentic resolves credentials and provides the workflow trigger schema so the agent only needs the workflow name and recipient ID. Example prompt: Search Jentic for 'send a multi-channel notification', load the Engagespot workflow trigger schema, and POST /notifications with workflow 'incident-alert' and recipientId 'oncall-eng' when a monitored signal fires ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/notifications` | Trigger a workflow run for one or more recipients | | GET | `/notifications` | List notifications sent to a user | | POST | `/notifications/delete-all` | Bulk delete notifications from a user inbox | | POST | `/users` | Create or upsert a recipient user | | DELETE | `/users` | Delete a recipient user | | PATCH | `/workflows/{workflowId}/cancel` | Cancel an in-flight workflow run | | GET | `/preferences` | Read a user's notification preferences | ## Key resources - **Notifications** — Trigger workflow runs, list past notifications, and bulk delete from a user inbox - **Users** — Create and delete recipient user records with channel identifiers - **Workflows** — Cancel in-flight workflow runs by workflowId - **Preferences** — Read user notification preferences across channels and categories ## Why Jentic - **Setup:** Wiring Engagespot by hand means sending both its X-ENGAGESPOT-API-KEY and X-ENGAGESPOT-API-SECRET headers and choosing between its US and EU hosts yourself. Through Jentic you install once, import the Engagespot API from the API Directory, store the credentials once, and your agent calls it. - **Permission scoping:** Engagespot puts the workflow id in the URL path (`/workflows/{workflowId}/cancel`), while notification and user targets travel in the request body, so limit the agent to the operations it needs, such as sending notifications and managing preferences, and leave user deletion out of the allowed set. Every operation you grant is your explicit choice. - **Credential handling:** Your Engagespot key and secret are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'send a transactional notification' or 'read a recipient's preferences', and Jentic returns the matching Engagespot operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Courier** — Multi-channel notification orchestration with similar workflow-based routing across email, SMS, push, and chat - **OneSignal** — Push and in-app messaging platform focused on mobile and web push at scale - **SendGrid** — Email delivery provider that Engagespot can route email channels through ## FAQ ### Why is there no official OpenAPI spec for Engagespot API? Engagespot does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Engagespot API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Engagespot API use? Engagespot uses two API key headers, X-ENGAGESPOT-API-KEY and X-ENGAGESPOT-API-SECRET, sent on every request. When you call Engagespot through Jentic, both keys are stored in your Jentic One instance and injected at execution time so they never enter the agent's context. ### Can I send a notification across multiple channels with one API call? Yes. POST /notifications triggers a workflow you have defined in the Engagespot dashboard, and the workflow itself decides which channels (in-app, email, SMS, push, Slack) fire for each recipient based on their preferences. You only pass the workflow identifier and recipient details. ### Can I cancel a notification after triggering it? Yes, for workflow runs that are still in flight (for example digesting or scheduled). Call PATCH `/workflows/{workflowId}/cancel` with the workflowId returned from the trigger call. Notifications already dispatched to channels cannot be recalled. ### How do I send a multi-channel notification through Jentic? Run pip install jentic, then search for 'send a multi-channel notification', load the Engagespot POST /notifications operation schema, and execute with workflow identifier and recipient. Jentic returns the response without you handling the X-ENGAGESPOT-API-KEY headers directly. ### What is the difference between users and preferences in this API? Users are recipient records (id, email, phone, timezone) created via POST /users. Preferences are the per-user, per-channel, per-category opt-in matrix read via GET /preferences. You manage recipient identity in /users and recipient consent in /preferences. ### Can I limit what my agent is allowed to do with the Engagespot API? Yes. Because Jentic One is self-hosted, you decide which Engagespot operations your agent may call, so you can grant it the endpoints it needs, such as POST /notifications to trigger a workflow and GET /preferences to read recipient settings, while withholding others. If deleting recipients is not part of the agent's job, you simply leave DELETE /users out of the allowed set, and it cannot reach it. Your own rules also govern which stored credentials the agent may use, so every operation it can perform is your explicit choice.