Approvals

An API key can be set to require approval. A send from that key is checked like any other, then stored and held instead of sent, and POST /v1/emails answers 202 with status: "pending_approval" and an approval_id. The approval is what a person decides on: approving releases the message, rejecting cancels it.

Approvals expire 72 hours after the send was requested. An expired approval drops out of the list and can no longer be decided, so a forgotten draft never goes out days later. A background job then marks it expired and its message canceled, usually within a minute; a message whose last release the provider refused keeps its failed status. The ideas, and what an agent should do with a held response, are on Approvals.

The approval object

Returned by the list endpoint.

message does not include from, cc, bcc, reply_to, attachments or the scheduled time. Retrieve the message with GET /v1/emails/{id} for from and scheduled_at.

List pending approvals

GET /v1/approvals · requires emails:read

Every approval in the workspace that is still pending and has not expired, oldest first. The list is not paged: it returns the envelope described in Pagination with next_cursor always null. Every pending approval is returned in data; when there are 500 or more, has_more is also true, even though nothing is left out.

Example

curl https://api.sendraven.ai/v1/approvals \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
      "message_id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
      "api_key_id": "6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c",
      "expires_at": "2026-09-18T12:00:00.000Z",
      "created_at": "2026-09-15T12:00:00.000Z",
      "message": {
        "to": ["ana@example.com"],
        "subject": "Re: Refund request",
        "text": "Hi Ana, I've issued a full refund. It should arrive within five working days.",
        "html": null
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Decide an approval

POST /v1/approvals/{id} · requires emails:send

Approves or rejects one held send. Only one decision can land: two reviewers deciding at the same moment cannot release the same message twice. A second decision after the first has completed gets 409 invalid_state; one that arrives while the first is still sending gets 409 approval_in_progress.

Who can decide. Approvals are decided by a person in the dashboard, or by an API key without guardrails. The call answers 403 forbidden when the credential is an OAuth access token (the credential an MCP client holds, which is an agent's by construction), when it is the key that made the draft, or when it is a key with guardrails of its own (requires_approval, a non-empty allowed_recipients or a daily_send_limit), so an agent cannot release its own mail or another agent's. Any other API key in the workspace with emails:send can decide. decided_by is recorded as given and is not verified.

Rejecting marks the message canceled. The send still counts against the key's daily cap, which is spent when a draft is held.

Approving releases the message. A draft can wait days, so what was true when it was held is checked again first:

• Suppressions and topic preferences, for every address in to, cc and bcc. An address suppressed or opted out while the draft waited is dropped. If no to address is left, nothing is sent, the message is recorded as rejected, and the approval is still approved; the response has skipped: true and a reason.
• The plan allowance, counted over the recipients left.

Then the message is released in one of two ways:

• If the send was made with a scheduled_at that is still in the future, the message is put on the schedule, its status becomes scheduled, and the response carries that scheduled_at. A hold cannot be walked around by scheduling, and approving does not bring the send forward. Suppressions, topic preferences and the plan allowance are checked once more when it comes due.
• Otherwise it is sent now, and scheduled_at in the response is null. A suspended workspace, a marketing workspace with no postal address and, for marketing mail, the sending domain's warm-up allowance are checked at this point.

The approval is only recorded as approved once the release has worked. If it fails, the call answers with the reason and the approval stays pending, so it can be approved again once the cause is fixed; it still expires at its original time. A message the provider refused is marked failed and a later approval tries it again. The key's allowlist and daily cap are not checked again: they were checked, and the cap spent, when the draft was held.

A released message updates its thread when the provider accepts it, which clears awaiting_reply.

Path parameters

Body

Example

curl -X POST https://api.sendraven.ai/v1/approvals/e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "decision": "approve",
    "decided_by": "ana@example.com"
  }'

Response

200 OK

Both decisions answer the same fields.

Approved:

{
  "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
  "status": "approved",
  "message_id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
  "scheduled_at": null,
  "skipped": false,
  "reason": null
}

Approved, but every to address was suppressed while the draft waited, so nothing was sent:

{
  "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
  "status": "approved",
  "message_id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
  "scheduled_at": null,
  "skipped": true,
  "reason": "suppressed:hard_bounce"
}

Rejected:

{
  "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
  "status": "rejected",
  "message_id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
  "scheduled_at": null,
  "skipped": false,
  "reason": null
}

Errors