Deliveries
Base URL: https://app.trymaglev.com/api/v1. All endpoint families.
GET /deliveries
Section titled “GET /deliveries”Your newest 100 matching outbound messages and their status. Count is the number returned; no pagination is currently exposed.
Returns at most the newest 100 matching deliveries. Count is the number returned, not the total saved. No pagination is currently exposed.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
status |
query | No |
200 response schema
{ "type": "object", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "count": { "type": "integer" }, "draft": { "const": true }, "requestId": { "type": "string" } }, "required": [ "deliveries", "count", "draft", "requestId" ]}Errors: 400 Invalid input or missing idempotency header; 401 Invalid key or missing sign-in; 403 Insufficient access; 429 Rate limit reached; 500 Server failure. See recovery guidance.
GET /deliveries/{id}
Section titled “GET /deliveries/{id}”One delivery and its recoverable email dispatch receipt. Provider acceptance is not confirmation of recipient delivery.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
id |
path | Yes |
200 response schema
{ "type": "object", "properties": { "delivery": { "$ref": "#/components/schemas/Delivery" }, "to": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "factoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "address", "factoryId" ] }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requestId": { "type": "string" }, "draft": { "const": true }, "dispatch": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "ready", "sending", "uncertain", "failed", "accepted" ] }, "attempts": { "type": "integer" }, "firstAttemptAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryBefore": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "leaseExpiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastOutcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerMessageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payloadSha256": { "type": "string" }, "providerAccepted": { "type": "boolean" }, "recipientDeliveryConfirmed": { "const": false }, "receipt": { "type": "object", "properties": { "scope": { "const": "provider_email" }, "providerDeliveryReported": { "type": "boolean" }, "events": { "type": "object", "properties": { "sent": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "delivered": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "delivery_delayed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "bounced": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "complained": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "failed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "suppressed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" } } }, "note": { "type": "string", "description": "Provider events do not prove individual copy-recipient delivery, reading, a reply or production acceptance." } }, "required": [ "scope", "providerDeliveryReported", "events", "note" ] } }, "required": [ "id", "status", "attempts", "firstAttemptAt", "retryBefore", "leaseExpiresAt", "lastOutcome", "providerMessageId", "acceptedAt", "payloadSha256", "providerAccepted", "recipientDeliveryConfirmed", "receipt" ] }, { "type": "null" } ] } }, "required": [ "delivery", "to", "cc", "subject", "bodyEn", "bodyZh", "status", "transport", "requestId", "draft", "dispatch" ]}Errors: 400 Validation error; 401 Missing or invalid key; 403 Scope or mode does not allow this; 404 Not found; 429 Rate limit reached. See recovery guidance.
GET /deliveries/{id}/review
Section titled “GET /deliveries/{id}/review”Read the exact current draft recipient, copy list, subject, bodies and project fingerprint before approval. Live key only. Resolves the current supplier contact but approves and sends nothing. Show the complete result to the principal; echo reviewSha256 as expectedReviewSha256 only after their approval. Changed content, contact or project invalidates that approval.
Required scope: approvals:write.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
id |
path | Yes |
200 response schema
{ "type": "object", "properties": { "review": { "type": "object", "properties": { "deliveryId": { "type": "string", "format": "uuid" }, "actionId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "projectVersion": { "type": "string" }, "channel": { "type": "string" }, "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "to": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "type": "string" }, "factoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "factoryName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "address", "factoryId", "factoryName" ] }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reviewSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "effect": { "type": "string" }, "note": { "type": "string" } }, "required": [ "deliveryId", "actionId", "projectId", "projectVersion", "channel", "from", "to", "cc", "subject", "bodyEn", "bodyZh", "reviewSha256", "effect", "note" ] } }, "required": [ "review" ]}Errors: 400 Validation error; 401 Missing or invalid key; 403 Scope or mode does not allow this; 404 Not found; 409 Draft or current recipient/context is unavailable for review; 429 Rate limit reached. See recovery guidance.
POST /deliveries/{id}/approve
Section titled “POST /deliveries/{id}/approve”Approve the exact reviewed draft by sending expectedReviewSha256 from GET /deliveries/{id}/review after principal approval. A first approval without it returns approval_review_required (409); changed recipient, content or context returns approval_review_changed (409). Sandbox cannot send. The exact factory address, copy list, subject and bodies are frozen with a provider idempotency key before sending. Missing contact or stale RFQ context returns 409 without approval. Repeating approval returns the saved state; use retry for an unresolved dispatch. Email without configured transport remains approved and unsent. WeChat remains explicitly manual. Provider acceptance is not delivery or a supplier reply.
Required scope: approvals:write.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
id |
path | Yes |
| Field | Type | Required | Details |
|---|---|---|---|
expectedReviewSha256 |
string | Yes | Pattern: ^[a-f0-9]{64}$ |
200 response schema
{ "type": "object", "properties": { "delivery": { "$ref": "#/components/schemas/Delivery" }, "to": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "factoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "address", "factoryId" ] }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requestId": { "type": "string" }, "dispatch": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "ready", "sending", "uncertain", "failed", "accepted" ] }, "attempts": { "type": "integer" }, "firstAttemptAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryBefore": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "leaseExpiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastOutcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerMessageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payloadSha256": { "type": "string" }, "providerAccepted": { "type": "boolean" }, "recipientDeliveryConfirmed": { "const": false }, "receipt": { "type": "object", "properties": { "scope": { "const": "provider_email" }, "providerDeliveryReported": { "type": "boolean" }, "events": { "type": "object", "properties": { "sent": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "delivered": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "delivery_delayed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "bounced": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "complained": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "failed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "suppressed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" } } }, "note": { "type": "string", "description": "Provider events do not prove individual copy-recipient delivery, reading, a reply or production acceptance." } }, "required": [ "scope", "providerDeliveryReported", "events", "note" ] } }, "required": [ "id", "status", "attempts", "firstAttemptAt", "retryBefore", "leaseExpiresAt", "lastOutcome", "providerMessageId", "acceptedAt", "payloadSha256", "providerAccepted", "recipientDeliveryConfirmed", "receipt" ] }, { "type": "null" } ] }, "note": { "type": "string" } }, "required": [ "delivery", "to", "cc", "subject", "bodyEn", "bodyZh", "status", "transport", "requestId", "dispatch", "note" ]}Errors: 400 Validation error; 401 Missing or invalid key; 403 Scope or mode does not allow this; 404 Not found; 409 Changed context, missing contact, unsafe retry, expired deduplication or changed provider identity; 429 Rate limit reached; 503 Provider outcome could not be persisted; read the saved delivery before recovering the same dispatch. See recovery guidance.
POST /deliveries/{id}/retry
Section titled “POST /deliveries/{id}/retry”Recover the same approved email dispatch. The exact payload and provider key are reused only after a 60-second worker lease and within 23 hours of the first attempt. Current caller and original approving keys, project context, payload and provider credential are rechecked. Expired deduplication or changed provider identity requires reconciliation, never blind resend. Legacy deliveries have no recoverable dispatch. Read GET /deliveries/{id} after an interrupted response.
Required scope: approvals:write.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
id |
path | Yes |
200 response schema
{ "type": "object", "properties": { "delivery": { "$ref": "#/components/schemas/Delivery" }, "to": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "factoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "address", "factoryId" ] }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requestId": { "type": "string" }, "dispatch": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "ready", "sending", "uncertain", "failed", "accepted" ] }, "attempts": { "type": "integer" }, "firstAttemptAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryBefore": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "leaseExpiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastOutcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerMessageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payloadSha256": { "type": "string" }, "providerAccepted": { "type": "boolean" }, "recipientDeliveryConfirmed": { "const": false }, "receipt": { "type": "object", "properties": { "scope": { "const": "provider_email" }, "providerDeliveryReported": { "type": "boolean" }, "events": { "type": "object", "properties": { "sent": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "delivered": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "delivery_delayed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "bounced": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "complained": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "failed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "suppressed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" } } }, "note": { "type": "string", "description": "Provider events do not prove individual copy-recipient delivery, reading, a reply or production acceptance." } }, "required": [ "scope", "providerDeliveryReported", "events", "note" ] } }, "required": [ "id", "status", "attempts", "firstAttemptAt", "retryBefore", "leaseExpiresAt", "lastOutcome", "providerMessageId", "acceptedAt", "payloadSha256", "providerAccepted", "recipientDeliveryConfirmed", "receipt" ] }, { "type": "null" } ] }, "note": { "type": "string" } }, "required": [ "delivery", "to", "cc", "subject", "bodyEn", "bodyZh", "status", "transport", "requestId", "dispatch", "note" ]}Errors: 400 Validation error; 401 Missing or invalid key; 403 Scope or mode does not allow this; 404 Not found; 409 Changed context, missing contact, unsafe retry, expired deduplication or changed provider identity; 429 Rate limit reached; 503 Provider outcome could not be persisted; read the saved delivery before recovering the same dispatch. See recovery guidance.
POST /deliveries/{id}/reject
Section titled “POST /deliveries/{id}/reject”Reject a draft delivery; bodies are kept for the record. Once approval has claimed the draft, dispatch may already be in flight and rejection returns 409. This endpoint cannot cancel an approved send.
Required scope: approvals:write.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
id |
path | Yes |
| Field | Type | Required | Details |
|---|---|---|---|
reason |
string | No | Max length 400 |
200 response schema
{ "type": "object", "properties": { "delivery": { "$ref": "#/components/schemas/Delivery" }, "to": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "factoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "name", "address", "factoryId" ] }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "delivery", "to", "cc", "subject", "bodyEn", "bodyZh", "status", "transport", "note", "requestId" ]}Errors: 400 Invalid input or missing idempotency header; 401 Invalid key or missing sign-in; 403 Insufficient access; 404 Endpoint or record unavailable; 409 Version, publication or idempotency conflict; 429 Rate limit reached; 500 Server failure. See recovery guidance.
GET /outbox
Section titled “GET /outbox”Live manual outbox deliveries across owners (Maglev keys only). Uncertain provider dispatches and legacy resend_failed messages are excluded. Use only the frozen approved recipient.
Required scope: maglev:*.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
status |
query | No | queued or needs_contact |
200 response schema
{ "type": "object", "properties": { "requestId": { "type": "string" } }}Errors: 400 Validation error; 401 Missing or invalid key; 403 Scope or mode does not allow this; 404 Not found; 429 Rate limit reached. See recovery guidance.
POST /deliveries/{id}/sent
Section titled “POST /deliveries/{id}/sent”Record a live addressed manual outbox delivery as sent (Maglev keys only). Provider dispatches and unknown outcomes are rejected; never use this endpoint to bypass provider reconciliation.
Required scope: maglev:*.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
id |
path | Yes |
| Field | Type | Required | Details |
|---|---|---|---|
sentBy |
string | Yes | Min length 1. Max length 120 |
reference |
string | No | For example the Gmail message id. Max length 200 |
200 response schema
{ "type": "object", "properties": { "delivery": { "$ref": "#/components/schemas/Delivery" }, "to": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "factoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "name", "address", "factoryId" ] }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "delivery", "to", "cc", "subject", "bodyEn", "bodyZh", "status", "transport", "note", "requestId" ]}Errors: 400 Invalid input or missing idempotency header; 401 Invalid key or missing sign-in; 403 Insufficient access; 404 Endpoint or record unavailable; 409 Version, publication or idempotency conflict; 429 Rate limit reached; 500 Server failure. See recovery guidance.