Email Sending API
Two endpoints handle email delivery through different providers.
POST /api/send-email
Primary sending endpoint using Resend.
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"
}'
| Field | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Recipient email address |
subject | string | Yes | Email subject line |
html | string | Yes | Full HTML email content |
senderEmail | string | No | Sender's email (for attribution banner) |
Response
{
"success": true,
"messageId": "re_abc123..."
}
Processing Pipeline
Before sending, the endpoint applies several transformations:
- Tracking pixel injection — Adds a 1x1 transparent pixel with mail merge variables:
{{UUID}}— Unique interaction ID{{SEND_ID}}— Send session ID{{TIMESTAMP}}— Send timestamp
- Image URL resolution — Converts relative image paths to absolute
https://kinetic.email/...URLs - Attribution banner — If the sender is not the recipient, an "Sent via Kinetic Email" banner is appended
- XSS sanitization — Sender email is HTML-escaped before insertion into the banner
POST /api/send-email-ses
Fallback sending endpoint using AWS SES.
Request
Same request format as /api/send-email.
Response
{
"success": true,
"messageId": "ses_xyz789..."
}
Token Cost
Both endpoints charge the email_send token action. The cost is defined in the token_action_costs table.
Error Handling
| Status | Error | Cause |
|---|---|---|
| 401 | Authentication required | Missing or invalid JWT |
| 402 | Insufficient tokens | Not enough tokens for email_send |
| 400 | Missing required fields | to, subject, or html not provided |
| 500 | Send failed | Resend/SES API error |