/magic-inboxes

post

https://api.dev.orbit.do/v5/magic-inboxes

Create a magic inbox. This also creates the inbound mailbox that receives its email; the mailbox id doubles as the local-part of the inbound address. The transport shape must be a managed shape or one this tenant owns.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

name

string

required

length between 1 and 100

Human-facing name of the magic inbox. 1–100 characters. The name is part of an index key, so longer values are rejected up front rather than failing in storage.

shapeId

string

required

Internal TransportShape id governing which fields are extracted and what a submitted draft creates. Required.

allowedEmailAddresses

array of strings

Allowlist of sender email addresses (SMTP from). Inbound mail is processed only when its sender matches an entry; when omitted, mail from any sender is accepted, and an empty list blocks every sender.

allowedEmailAddresses

presets

object

Fixed per-field values that overwrite whatever the AI extracted, keyed by transport field path. Applied after extraction.

fallbacks

object

Default per-field values used only where the AI extracted nothing, keyed by transport field path. Never overwrite an extracted value.

magicFields

array of objects

Custom LLM extraction prompts, each targeting one transport field or tenant property. The target must be enabled in the TransportShape to take effect.

magicFields

customInstructions

string

Free-text instructions appended to the AI extraction prompt for this inbox.

autoAction

string | null

Deprecated. Use enableAutoResolveRFQ, enableAutoRFQ, enableAutoBook, or enableAutoBookElseDelete instead.

identificationMode

string

enum

Defaults to force-booking

How inbound emails are classified: 'auto' lets the AI decide booking vs. price request; 'force-rfq' treats all as quote requests; 'force-booking' (default) treats all as bookings. Sets the resulting draft's review-order vs. review-rfq status.

Allowed:

decodePipelineMode

string

enum

Defaults to internal

Which decode extractor processes this inbox's emails. Only 'internal' is operational; the retired extractor is no longer accepted.

Allowed:

enableAutoResolveRFQ

boolean

Defaults to false

When a decoded draft is not base-validated, automatically emails the shipper asking them to complete the missing details via Orbit Hub.

enableAutoRFQ

boolean

Defaults to false

When a decoded draft is base-validated and has at least one product, automatically sends the shipper a price offer.

enableAutoBook

boolean

Defaults to false

When a decoded draft is fully validated, automatically submits the transport and creates the Order without operator review.

enableAutoBookElseDelete

boolean

Defaults to false

Refines enableAutoBook: a draft that is not fully validated is deleted instead of being left for review. Requires enableAutoBook.

enablePreferDirectSender

boolean

Defaults to false

When set, shipper matching prefers the direct sender (SMTP from) over a forwarded-from address extracted from the email body.

orderDocumentTypes

array of strings

Defaults to []

MIME types of email content auto-attached as Documents on the created Order; the special 'emailPdf' value attaches a PDF rendering of the email itself. Attached documents are operator-only: hidden from carrier and shipper. Defaults to none.

orderDocumentTypes

Responses

400

Bad request: body validation failure

401

unauthorized

404

Transport shape not found

Language

Credentials

Header

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200The created magic inbox