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 | One delivery status. Omitted returns every status.. One of: draft, approved, queued, needs_contact, sending, delivery_unknown, delivery_failed, sent, rejected |
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" } ] }, "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" } ] }, "requestId": { "type": "string", "description": "Echoed in the X-Request-Id response header. Quote it to Maglev when asking what became of a request." } }, "required": [ "delivery", "to", "cc", "subject", "bodyEn", "bodyZh", "status", "transport", "draft", "dispatch", "requestId" ]}Errors: 400 Validation error; 401 unauthorized: no bearer key was presented, or the one presented is unknown, expired or revoked. Present a valid key; nothing was done.; 403 Scope or mode does not allow this. On scope_required, details.obtainable says whether a key that carries the scope can be issued at all: true means reissuing this key with the scope would work, false means no key of this kind can ever carry it, because contacts:read and approvals:write are granted on live mode alone and maglev:* belongs to Maglev’s own keys. Stored scopes narrow the grant a mode and organisation already allow, so widening a key never adds one.; 404 Not found; 429 rate_limit: a limit for this key or route is spent. details.retryAfter is how many whole seconds of the refused window remain, at least 1, and the Retry-After header carries the same number. Wait that long rather than assuming a minute; the windows here range from 60 to 86400 seconds. Nothing was done.; 500 internal_error: the request did not complete and the reason was not one this API anticipates. Whether anything was written is unknown. Read error.message, which carries what is safe to do next, and quote the X-Request-Id header to Maglev; the request id is in the body too. Where an operation takes an Idempotency-Key, repeating the request with the same key is the way to learn the earlier outcome without running the work twice, unless the message says to use a new one.. 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" ] }, "requestId": { "type": "string", "description": "Echoed in the X-Request-Id response header. Quote it to Maglev when asking what became of a request." } }, "required": [ "review", "requestId" ]}Errors: 400 Validation error; 401 unauthorized: no bearer key was presented, or the one presented is unknown, expired or revoked. Present a valid key; nothing was done.; 403 Scope or mode does not allow this. On scope_required, details.obtainable says whether a key that carries the scope can be issued at all: true means reissuing this key with the scope would work, false means no key of this kind can ever carry it, because contacts:read and approvals:write are granted on live mode alone and maglev:* belongs to Maglev’s own keys. Stored scopes narrow the grant a mode and organisation already allow, so widening a key never adds one.; 404 Not found; 409 Nothing is approved or sent by any of these. invalid_status: only a draft delivery can be reviewed, so read the saved receipt instead. stale_project_context: the requirements changed or this RFQ has no current project snapshot, so generate and review a new quote_request. unsupported_channel: this delivery channel is not supported. missing_contact: the factory has no address for this channel, so add and review its contact first. invalid_delivery: the recipient, copy list, subject or message is unusable; 429 rate_limit: a limit for this key or route is spent. details.retryAfter is how many whole seconds of the refused window remain, at least 1, and the Retry-After header carries the same number. Wait that long rather than assuming a minute; the windows here range from 60 to 86400 seconds. Nothing was done.; 500 internal_error: the request did not complete and the reason was not one this API anticipates. Whether anything was written is unknown. Read error.message, which carries what is safe to do next, and quote the X-Request-Id header to Maglev; the request id is in the body too. Where an operation takes an Idempotency-Key, repeating the request with the same key is the way to learn the earlier outcome without running the work twice, unless the message says to use a new one.. 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 | No | reviewSha256 from GET /deliveries/{id}/review, after the principal approved what it showed. Mandatory on a first approval, which refuses with approval_review_required (409) without it. Not required to replay the approval of a delivery this key already approved, because that returns the saved receipt without re-reviewing anything, so a client recovering from a lost response can call this again with an empty body.. 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" } ] }, "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" }, "requestId": { "type": "string", "description": "Echoed in the X-Request-Id response header. Quote it to Maglev when asking what became of a request." } }, "required": [ "delivery", "to", "cc", "subject", "bodyEn", "bodyZh", "status", "transport", "dispatch", "note", "requestId" ]}Errors: 400 Validation error. A body is read here, so one of five codes rides on this status and none is retryable unchanged. validation_error: the body parsed and failed the schema, and details names each path. invalid_json: there was no body, or it was not valid UTF-8 JSON. invalid_text: a string or property name holds a NUL or an unpaired Unicode surrogate, which storage cannot keep, so correct the source text. duplicate_key: a JSON object repeats a property name, no path is given, and the conflicting fields have to be resolved at the source. invalid_number: a number is outside the range that survives the round trip, so quote large identifiers as strings. Nothing was written in any of them.; 401 unauthorized: no bearer key was presented, or the one presented is unknown, expired or revoked. Present a valid key; nothing was done.; 403 Scope or mode does not allow this. On scope_required, details.obtainable says whether a key that carries the scope can be issued at all: true means reissuing this key with the scope would work, false means no key of this kind can ever carry it, because contacts:read and approvals:write are granted on live mode alone and maglev:* belongs to Maglev’s own keys. Stored scopes narrow the grant a mode and organisation already allow, so widening a key never adds one.; 404 Not found; 409 Nothing is sent by any of these, and they differ in what is safe next, so branch on error.code. approval_review_required: send expectedReviewSha256 from GET /deliveries/{id}/review. approval_review_changed: the recipient, message or project changed after review, so read and confirm a new review. invalid_status: this delivery is not in a state that allows approval or dispatch. stale_project_context: the requirements changed, so inspect the existing provider outcome before preparing a replacement. unsupported_channel: this delivery channel is not supported. missing_contact: the factory has no address for this channel. invalid_delivery: the recipient, copy list, subject or message is unusable. dispatch_failed: the provider rejected it, and it will not be resent automatically, so prepare a new draft. dispatch_payload_changed: the saved message no longer matches its approval. delivery_reconciliation_required: the provider deduplication window expired, so reconcile with the provider and do not resend. provider_identity_changed: the provider credential changed, so deduplication cannot be assumed across accounts. On the last three a resend could reach the factory twice. no_recoverable_dispatch is not reachable here; it belongs to POST /deliveries/{id}/retry; 413 body_too_large: the request body exceeds this operation’s limit, and it was not read to the end. Send less in one request rather than repeating it; 415 content_type: the request did not declare application/json, so no body was read and nothing was written. Set the header and send it again; 429 rate_limit: a limit for this key or route is spent. details.retryAfter is how many whole seconds of the refused window remain, at least 1, and the Retry-After header carries the same number. Wait that long rather than assuming a minute; the windows here range from 60 to 86400 seconds. Nothing was done.; 500 internal_error: the request did not complete and the reason was not one this API anticipates. Whether anything was written is unknown. Read error.message, which carries what is safe to do next, and quote the X-Request-Id header to Maglev; the request id is in the body too. Where an operation takes an Idempotency-Key, repeating the request with the same key is the way to learn the earlier outcome without running the work twice, unless the message says to use a new one.; 503 delivery_receipt_pending: the provider call finished and its receipt could not be saved, so the message may already be on its way. Read GET /deliveries/{id} and recover the same dispatch after its lease expires; never create a replacement because this response failed. 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" } ] }, "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" }, "requestId": { "type": "string", "description": "Echoed in the X-Request-Id response header. Quote it to Maglev when asking what became of a request." } }, "required": [ "delivery", "to", "cc", "subject", "bodyEn", "bodyZh", "status", "transport", "dispatch", "note", "requestId" ]}Errors: 400 Validation error; 401 unauthorized: no bearer key was presented, or the one presented is unknown, expired or revoked. Present a valid key; nothing was done.; 403 Scope or mode does not allow this. On scope_required, details.obtainable says whether a key that carries the scope can be issued at all: true means reissuing this key with the scope would work, false means no key of this kind can ever carry it, because contacts:read and approvals:write are granted on live mode alone and maglev:* belongs to Maglev’s own keys. Stored scopes narrow the grant a mode and organisation already allow, so widening a key never adds one.; 404 Not found; 409 Nothing is resent by any of these, and they differ in what is safe next, so branch on error.code. no_recoverable_dispatch: a manual or legacy delivery with no saved provider dispatch, so inspect its status and do not resend an uncertain legacy email. dispatch_failed: the provider rejected it, and it will not be resent automatically, so prepare a new draft. invalid_status: this delivery is not approved for provider dispatch. stale_project_context: the requirements changed after approval, so inspect the existing provider outcome before preparing a replacement. dispatch_payload_changed: the saved message no longer matches its approval. delivery_reconciliation_required: the provider deduplication window expired, so reconcile with the provider and do not resend. provider_identity_changed: the provider credential changed, so deduplication cannot be assumed across accounts. The last three each mean a resend could reach the factory twice; 429 rate_limit: a limit for this key or route is spent. details.retryAfter is how many whole seconds of the refused window remain, at least 1, and the Retry-After header carries the same number. Wait that long rather than assuming a minute; the windows here range from 60 to 86400 seconds. Nothing was done.; 500 internal_error: the request did not complete and the reason was not one this API anticipates. Whether anything was written is unknown. Read error.message, which carries what is safe to do next, and quote the X-Request-Id header to Maglev; the request id is in the body too. Where an operation takes an Idempotency-Key, repeating the request with the same key is the way to learn the earlier outcome without running the work twice, unless the message says to use a new one.; 503 delivery_receipt_pending: the provider call finished and its receipt could not be saved, so the message may already be on its way. Read GET /deliveries/{id} and recover the same dispatch after its lease expires; never create a replacement because this response failed. 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 when omitted, which is a filter rather than the whole outbox.. One of: queued, needs_contact. Default: “queued” |
200 response schema
{ "type": "object", "properties": { "outbox": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Delivery" }, { "type": "object", "properties": { "factoryName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "factoryNameZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipient": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "description": "toName on the delivery, or the factory contact name when the delivery froze none" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string", "description": "The frozen approved address. Send to this and nothing else" }, { "type": "null" } ] } } }, "mailText": { "type": "string", "description": "bodyZh and bodyEn joined, in that order, which is the text to send. Built here so an operator does not assemble it by hand and reorder the two" } } } ] } }, "count": { "type": "integer" }, "sender": { "type": "string", "description": "The From line to send as" }, "note": { "type": "string" }, "requestId": { "type": "string", "description": "Echoed in the X-Request-Id response header. Quote it to Maglev when asking what became of a request." } }, "required": [ "requestId" ]}Errors: 400 Validation error; 401 unauthorized: no bearer key was presented, or the one presented is unknown, expired or revoked. Present a valid key; nothing was done.; 403 Scope or mode does not allow this. On scope_required, details.obtainable says whether a key that carries the scope can be issued at all: true means reissuing this key with the scope would work, false means no key of this kind can ever carry it, because contacts:read and approvals:write are granted on live mode alone and maglev:* belongs to Maglev’s own keys. Stored scopes narrow the grant a mode and organisation already allow, so widening a key never adds one.; 404 Not found; 429 rate_limit: a limit for this key or route is spent. details.retryAfter is how many whole seconds of the refused window remain, at least 1, and the Retry-After header carries the same number. Wait that long rather than assuming a minute; the windows here range from 60 to 86400 seconds. Nothing was done.; 500 internal_error: the request did not complete and the reason was not one this API anticipates. Whether anything was written is unknown. Read error.message, which carries what is safe to do next, and quote the X-Request-Id header to Maglev; the request id is in the body too. Where an operation takes an Idempotency-Key, repeating the request with the same key is the way to learn the earlier outcome without running the work twice, unless the message says to use a new one.. 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.