HTTP API

API reference

Request and response details for email submission and service health.

POST /v1/emails

Validates a message and submits it through the configured SMTP server.

Headers

Required headers

Content-Type: application/json
X-API-Key: YOUR_API_KEY

Request body

json

{
  "from_email": "notifications@yourdomain.com",
  "from_name": "Your Company",
  "recipient_email": ["customer@example.com"],
  "subject": "Welcome",
  "body": "<h1>Welcome!</h1><p>Your account is ready.</p>",
  "body_type": "html",
  "reply_to": "support@yourdomain.com"
}

Fields

Field	Rules
`recipient_email`	Required array containing 1–50 valid email addresses.
`subject`	Required string, maximum 255 characters.
`body`	Required string, maximum 1 MB.
`body_type`	Either plain or html.
`from_email`	Optional valid address using an allowed domain; controls the visible sender.
`from_name`	Optional visible sender name.
`reply_to`	Optional valid email address.

Success response

json

{
  "status": "success",
  "message": "Email accepted by SMTP server"
}

Status codes

200 — SMTP server accepted the message.
401 — API key is missing or invalid.
422 — Validation failed or the sender domain is not allowed.
502 — SMTP connection, authentication, or submission failed.
503 — Required service configuration is incomplete.

Health endpoints

GET /healthz reports whether the process is alive. GET /readyz reports whether required configuration is present and the service can accept work. Neither endpoint sends a test email.

Legacy route

POST /send-email remains available for compatibility. New integrations should use POST /v1/emails.

Request IDs

Responses include an X-Request-ID header. Record it with application errors so a request can be correlated with OwnSMTP logs.