API reference

Request anatomy

Build requests from the versioned base URL, a scoped bearer key, and JSON only when a body is present.

curl -X POST https://sendix.dev/api/v1/emails \
  -H "Authorization: Bearer $SENDIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Request-Id: checkout-order_9f83a2" \
  -H "Idempotency-Key: order_9f83a2-receipt" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Your receipt",
    "text": "Thank you for your order."
  }'

The API also accepts a valid X-Correlation-Id when X-Request-Id is absent. Sendix reflects the selected ID in the response. Do not place credentials or sensitive recipient data in either identifier.

Responses

Branch on the HTTP status first, then use the machine-readable error code.

201 Created
X-Request-Id: checkout-order_9f83a2
Content-Type: application/json

{ "id": "2f0b4d7e-..." }

400 Bad Request
X-Request-Id: checkout-order_9f83a2
Content-Type: application/json

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request",
    "details": { "fieldErrors": { "to": ["Invalid email"] } },
    "request_id": "checkout-order_9f83a2"
  }
}

A 200 or 201 response contains JSON. 202 means asynchronous work was accepted, not completed. 204 has no response body. Error responses use an error object; validation and domain errors can add details, and server-generated errors include a correlation request ID.

Safe mutations

Email creation

Use one stable Idempotency-Key per logical email. It must be 8–128 characters using letters, digits, dot, underscore, colon, or hyphen. The body field idempotency_key is equivalent; if both are sent, they must match.

Updates and deletes

Read the current resource state before workflows that depend on it, then handle 404 and 409 explicitly. For example, only a scheduled email can be rescheduled or cancelled; a worker may advance its state between your read and mutation.

Attachments and images

Send files and images by passing base64-encoded attachment objects to POST /emails.

Sendix accepts up to 20 attachments per message, with a 10 MB limit per file and 25 MB total attachment limit. Executable and script-like attachment types are blocked to reduce abuse and mailbox-provider risk.

curl -X POST https://sendix.dev/api/v1/emails \
  -H "Authorization: Bearer $SENDIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Invoice",
    "text": "Your invoice is attached.",
    "attachments": [
      {
        "filename": "invoice.pdf",
        "contentType": "application/pdf",
        "content": "JVBERi0xLjQK..."
      },
      {
        "filename": "receipt.png",
        "contentType": "image/png",
        "content": "iVBORw0KGgo..."
      }
    ]
  }'

Spam risk check

Use POST /emails/spam-check before a large rollout or template launch.

The endpoint returns a score, triggered rules, recommendations, and a sendability flag. It does not replace SPF, DKIM, DMARC, clean lists, or gradual warmup; it gives developers a fast preflight signal before submitting real traffic.

curl -X POST https://sendix.dev/api/v1/emails/spam-check \
  -H "Authorization: Bearer $SENDIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "subject": "Your invoice is ready",
    "html": "<p>Your invoice is attached.</p>",
    "text": "Your invoice is attached."
  }'