EntryGoDocs
QuickstartProtocolAPI Reference

Concept

Broker Submission

Broker submission is the protocol-managed step where EntryGo hands an executed export package to the broker-facing delivery flow.

The important architectural rule is that broker handling belongs inside the protocol, not inside every client.

#Current model

In the current implementation, export execution performs broker coordination by:

  1. generating or locating the customs package
  2. collecting artifact metadata
  3. preparing a broker submission record
  4. sending the current email-oriented submission
  5. recording status, timestamps, and any error state

That broker submission record is then surfaced in execute and inspect responses.

#Broker submission fields

The current protocol exposes a stable broker submission view with fields such as:

  • identifier
  • submission_type
  • status
  • recipient_email
  • subject
  • sent_at
  • error_message

Those fields let clients answer a narrow but important question: "What happened to broker delivery for this export?"

#Why this belongs in the protocol

If broker communication lived outside EntryGo:

  • each integration would invent its own delivery semantics
  • execute would stop being the true side-effect boundary
  • inspect could not explain the full operational outcome
  • AI agents would need private knowledge outside the public contract

By keeping broker submission in the protocol:

  • execution remains the single place where broker side effects happen
  • inspect remains the single place where current broker state is observed
  • future transport changes can happen without breaking the export lifecycle

#Why email is acceptable today

Email is the current transport because it is operationally simple and preserves the right contract boundary.

The important product decision is not "email forever." The important decision is "broker delivery is modeled and auditable inside EntryGo."

That gives the platform:

  • a real downstream delivery step
  • observable status
  • retry and failure surfaces
  • room to evolve toward direct broker APIs later

#Relationship to execute and inspect

#Execute

Execution creates or updates broker submission state as part of the side-effecting export operation.

#Inspect

Inspection returns the latest broker submission state so callers can reconcile current delivery outcome without assuming the original execute response is still current.

#What clients should do

Human developers, SDK users, and AI agents should all follow the same rule:

  1. execute through the protocol
  2. inspect broker submission state through the protocol
  3. do not treat broker communication as an undocumented side channel

#Future transport evolution

EntryGo can later support:

  • direct broker APIs
  • structured submission gateways
  • broker-specific acknowledgements
  • richer receipt handling

Those changes should remain hidden behind the same top-level concept:

  • execute triggers broker handling
  • broker submission records the state
  • inspect returns the latest broker outcome

That continuity is why BrokerSubmission is already a first-class protocol primitive.