API Reference

Send an email

Queues a single email for delivery. The call returns immediately with a MessageID you can trace in the dashboard or the Messages endpoints below.

POST /email

response.json

{
  "To": "[email protected]",
  "SubmittedAt": "2025-01-14T09:30:00Z",
  "MessageID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "ErrorCode": 0,
  "Message": "OK"
}

Send batch

Sends up to 500 messages in one call. Each item is validated independently — one bad recipient never sinks the other 499.

POST /email/batch

response.json

[
  {
    "To": "[email protected]",
    "MessageID": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "ErrorCode": 0,
    "Message": "OK"
  },
  {
    "To": "not-an-email",
    "MessageID": null,
    "ErrorCode": 422,
    "Message": "Invalid 'To' address"
  }
]

Get a message

Fetches one message by ID, including its full content, tracking settings and delivery timestamps.

GET /messages/{id}

message.json

{
  "MessageID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "Status": "Delivered",
  "From": "[email protected]",
  "To": "[email protected]",
  "Subject": "Your receipt is ready",
  "ReceivedAt": "2025-01-14T09:30:01Z",
  "DeliveredAt": "2025-01-14T09:30:02Z",
  "TrackOpens": true,
  "TrackLinks": "HtmlAndText"
}

List messages

Pages through your outbound history, newest first. Filter by stream, status or recipient with query parameters.

GET /messages

messages.json

{
  "TotalCount": 2,
  "Messages": [
    {
      "MessageID": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "To": "[email protected]",
      "Subject": "Welcome aboard",
      "Status": "Delivered",
      "ReceivedAt": "2025-01-14T09:30:01Z"
    },
    {
      "MessageID": "d4e5f6a7-b8c9-0123-def1-234567890123",
      "To": "[email protected]",
      "Subject": "Weekly digest",
      "Status": "Queued",
      "ReceivedAt": "2025-01-14T09:31:12Z"
    }
  ]
}

Outbound stats

Aggregated sending statistics for a stream over a date range — the numbers that fit on one dashboard tile.

GET /stats/outbound

stats.json

{
  "Sent": 48210,
  "Delivered": 48001,
  "Bounced": 209,
  "Opens": 31240,
  "Clicks": 6112,
  "SpamComplaints": 3
}

Webhook payload

When PostedApi receives an email at your inbound domain, we parse it and POST the payload below to the webhook URL configured on the stream.

POST /messages/inbound

payload.json

{
  "From": "[email protected]",
  "To": "[email protected]",
  "Subject": "Question about my invoice",
  "TextBody": "Hi! Quick question about my last invoice...",
  "HtmlBody": "<p>Hi! Quick question about my last invoice...</p>",
  "Attachments": [
    {
      "Name": "invoice.pdf",
      "ContentType": "application/pdf",
      "ContentLength": 48211
    }
  ]
}

Errors

Errors come back as JSON with a machine-readable ErrorCode and a human-readable Message. The HTTP status tells you who to blame.

Code	Meaning
`400`	Bad request — the JSON was malformed or a required field is missing
`401`	Invalid token — check your `X-PostedApi-Server-Token` header
`422`	Validation failed — the request parsed, but a field was rejected
`429`	Rate limit exceeded — retry after the `Retry-After` header value
`500`	Server error — our side; retry with exponential backoff

Example error body:

error.json

{
  "ErrorCode": 422,
  "Message": "Invalid 'To' address"
}

Rate limits

The API allows 10 requests per second per server token. Exceed that and you'll get a 429 — honor the Retry-After response header (a delay in seconds) and retry once it counts down.