Documentation Home KeepSafe Messenger Home

Email Messages API

Base URL: https://messenger.keepsafe.ai

Authentication

App API calls use an app API token generated from the admin setup flow. Send it as a bearer token.

Authorization: Bearer <API_TOKEN>

Scope	Purpose
`device:write`	Register or update device push tokens, ActivityKit Live Activity push tokens, SMS recipients, and email recipients.
`slack:write`	Register or update Slack incoming webhook recipients.
`push:send`	Initiate push notifications and Live Activity updates.
`sms:send`	Initiate SMS messages through AWS End User Messaging.
`email:send`	Initiate email messages through SendGrid.
`slack:send`	Initiate Slack messages through registered incoming webhooks.
`admin`	Admin-level API access.

Register Email Recipient

POST /api/email/register

curl -X POST https://messenger.keepsafe.ai/api/email/register \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"appId":"APP_ID","recipientId":"user-123","email":"person@example.com","label":"Jon"}'

Field	Required	Notes
`appId` or `bundleId`	Yes	Use the app ID from admin or the bundle/package ID.
`recipientId`	Yes	Unique ID for this email recipient within the app. Specific email sends use this value, not the email address. Aliases: `recipientKey` or `externalId`.
`email`	Yes	Email address to register for this app. Stored event history exposes previews only.
`label`	No	Optional name or recipient label for the admin recipient table.

Send Email

POST /api/email/send

Specific Recipient IDs

curl -X POST https://messenger.keepsafe.ai/api/email/send \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"appId":"APP_ID","recipientIds":["user-123"],"subject":"Hello","message":"Hello from KeepSafe Messenger","dryRun":true}'

Broadcast

curl -X POST https://messenger.keepsafe.ai/api/email/send \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"appId":"APP_ID","target":{"type":"broadcast"},"subject":"Hello","message":"Hello registered recipients"}'

Field	Required	Notes
`appId` or `bundleId`	Yes	Identifies the app that owns the send event.
`recipientId`, `recipientIds`, or `target.recipientIds`	No	Specific send target. Every ID must already be registered for this app.
`target.type`	No	Use `broadcast` to send to all registered email recipients for the app. Specific sends use recipient IDs, not email addresses.
`subject` or `title`	Yes	Email subject.
`message` or `body`	No	Plain-text body. Required unless `html` is present.
`html` or `htmlBody`	No	Optional HTML body. Required unless plain text is present.
`dryRun`	No	Set `true` to record the email event without calling SendGrid.