API reference / Send a message

POST /v1/send

Send a message

Queues one message for delivery. The domain in from must be verified on your account; an unverified domain is rejected rather than sent unsigned.

Pass an Idempotency-Key header on anything you might retry. A repeated request with the same key returns the original response instead of sending twice.

Body parameters

from string required: Sender address on a verified domain. Accepts Name <addr@domain>.
to string | string[] required: One recipient or an array. Each recipient counts once against your monthly volume.
subject string required: Subject line.
html string optional: HTML body. Supply html, text or template — at least one.
text string optional: Plain-text alternative. Generated from the HTML when omitted.
tags string[] optional: Labels carried into the event log and every webhook for this message.
headers object optional: Custom headers. Authentication headers are set by Pharos and cannot be overridden.

Errors

CodeTypeMeaning

400 invalid_request A field is missing or malformed. The response names it.

401 invalid_key The key is wrong, revoked, or scoped to another domain.

403 domain_unverified The sending domain has not passed verification.

422 recipient_suppressed On your suppression list. Not sent, and not counted against your volume.

429 rate_limited Above 5 messages/second. Retry-After says when to resume.

RequestcURL

curl -X POST https://api.pharos.email/v1/send \
  -H "Authorization: Bearer $PHAROS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4471" \
  -d '{
    "from": "receipts@yourapp.com",
    "to": "customer@example.com",
    "subject": "Your receipt from Acme",
    "html": "<p>Thanks for your order.</p>",
    "tags": ["receipt"]
  }'

Response202 Accepted

{
  "id":     "msg_2f8Kq1Zx",
  "status": "queued",
  "dkim":   "signed",
  "dmarc":  "aligned"
}

Error response403 Forbidden

{
  "error": {
    "type":    "domain_unverified",
    "message": "yourapp.com is not verified",
    "field":   "from",
    "docs":    "/docs/domains"
  }
}