Skip to main content

Email Sending API

Two endpoints handle email delivery through different providers depending on whether AMP4Email is included.

POST /api/send-email​

Non-AMP sending endpoint using Resend. Used by the AI Playground (when AMP is not enabled), Portfolio, Learn modules, Blog, and all other pages.

Request​

curl -X POST https://kinetic.email/api/send-email \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Check out this kinetic email!",
    "html": "<!DOCTYPE html>...",
    "senderEmail": "sender@example.com"
  }'
FieldTypeRequiredDescription
tostringYesRecipient email address
subjectstringYesEmail subject line
htmlstringYesFull HTML email content
senderEmailstringNoSender's email (for attribution banner)

Response​

{
  "success": true,
  "message": "Email sent successfully!"
}

Processing Pipeline​

Before sending, the endpoint applies several transformations:

  1. View in Browser URL — Replaces {{VIB_URL}} with https://kinetic.email/view/{sendId} for the hosted email page
  2. Tracking pixel injection — Replaces mail merge variables in tracking pixel URLs:
    • {{UUID}} — SHA-256 hash of recipient email (consistent across sends)
    • {{SEND_ID}} — Unique UUID for this specific send
    • {{TIMESTAMP}} — Server-side epoch timestamp
    • {{VIB_URL}} — Hosted View in Browser page URL
  3. Image URL resolution — Converts relative image paths to absolute https://kinetic.email/... URLs
  4. Attribution banner — If the sender is not the recipient, a "Sent via Kinetic Email" banner is appended
  5. XSS sanitization — Sender email is HTML-escaped before insertion into the banner
  6. Convex logging — Logs the send to email_sends with full HTML content for View in Browser retrieval

POST /api/send-email-mailgun​

AMP4Email sending endpoint using Mailgun. Used by the AI Playground (when AMP is enabled) and the Station Sandbox.

Sends emails as raw MIME via Mailgun's messages.mime REST API, which supports the text/x-amp-html MIME part required for AMP4Email.

Request​

curl -X POST https://kinetic.email/api/send-email-mailgun \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Interactive AMP email!",
    "html": "<!DOCTYPE html>...",
    "ampHtml": "<!doctype html><html ⚡4email>...",
    "senderEmail": "sender@example.com",
    "databaseId": "optional-workspace-id"
  }'
FieldTypeRequiredDescription
tostringYesRecipient email address
subjectstringNoEmail subject line (defaults to "Your Kinetic Email")
htmlstringYesFull HTML email content (fallback for non-AMP clients)
ampHtmlstringNoAMP4Email HTML content
senderEmailstringYesSender's email (for attribution + tracking)
databaseIdstringNoConvex workspace ID for multi-tenant tracking

Response​

{
  "success": true,
  "message": "Email sent successfully via Mailgun!"
}

MIME Structure​

When ampHtml is provided, the email is sent as multipart/alternative with three MIME parts:

multipart/alternative
├── text/plain          (plain text fallback)
├── text/x-amp-html     (AMP version — rendered in Gmail, Yahoo)
└── text/html           (HTML fallback — rendered in all other clients)

When no ampHtml is provided, the same MIME structure is used without the AMP part.

Processing Pipeline​

Same as /api/send-email plus:

  1. Suppression check — Checks email_suppressions and email_bounce_log tables before sending
  2. AMP HTML processing — Relative URLs resolved, tracking placeholders replaced in AMP content
  3. Raw MIME assembly — Builds RFC 2822 compliant MIME message
  4. Convex logging — Logs send event to real-time tracking database

POST /api/mailgun-webhook​

Webhook endpoint for Mailgun delivery events. Not called directly — Mailgun POSTs to this endpoint when delivery events occur.

Events Handled​

EventAction
deliveredLogged to email_delivery_events
failed (permanent)Logged + recipient added to email_suppressions
failed (temporary)Logged to email_bounce_log with escalation (4+ = permanent suppress)
complainedLogged + recipient permanently suppressed
openedLogged to email_delivery_events
clickedLogged to email_delivery_events

All events trigger Telegram alerts for bounces and complaints.

Webhook Verification​

If MAILGUN_WEBHOOK_SIGNING_KEY is set, the endpoint verifies the HMAC-SHA256 signature on every request using Mailgun's timestamp + token signing scheme.

Token Cost​

Both send endpoints charge the email_send token action. The cost is defined in the token_action_costs table.

Error Handling​

StatusErrorCause
401Authentication requiredMissing or invalid JWT
402Insufficient tokensNot enough tokens for email_send
400Missing required fieldsto or html not provided
400Recipient suppressedRecipient is on the suppression list
500Send failedResend/Mailgun API error