POST

/v1/send

Unified endpoint to send a message on any channel.

Endpoint

POST https://api.yoursend.dev/v1/send

Requires an Authorization: Bearer ys_live_... header. Use a ys_test_... key to run in sandbox mode — requests are validated and logged but nothing is delivered or billed.

Request Body

Field	Type	Required	Description
channel	string	Yes	"email" \| "sms" \| "voice" \| "whatsapp" \| "auto"
to	string	Yes	Recipient (email or E.164 phone)
subject	string	Cond.	Email subject (or comes from the template)
html	string	Cond.	HTML body (email only)
text	string	No	Plain text body (email fallback)
body	string	Cond.	Message body (SMS/voice/WhatsApp)
template_id	string	Cond.	Template ID (alternative to inline content)
data	object	No	Merge-tag values for {{...}} placeholders
fallback	string	No	Channel to try if the primary one fails
fallback_to	string	No	Address for the fallback channel
media_urls	array	No	Up to 10 https media URLs (MMS/RCS/WhatsApp)

Omit subject, html, text, body, and template_id to send an OTP — YourSend generates and delivers the code. The sender address comes from your verified domain; there is no from field.

Response

200 OK

{
  "message_id": "8f14e45f-ceea-467a-9b3a-1d2c3e4f5a6b",
  "status": "sent",
  "channel": "email",
  "to": "user@example.com"
}

400 Bad Request

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: to",
    "status": 400
  }
}

403 Forbidden

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "status": 403
  }
}

Examples

Send email

curl -X POST https://api.yoursend.dev/v1/send \
  -H "Authorization: Bearer ys_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "to": "user@example.com",
    "subject": "Welcome!",
    "html": "<h1>Hello</h1>"
  }'

Send SMS OTP

No body or template means YourSend generates and sends the code.

curl -X POST https://api.yoursend.dev/v1/send \
  -H "Authorization: Bearer ys_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+14155551234"
  }'