US CBP Cargo Systems Messaging Service Change Signals

Monitor official U.S. Customs and Border Protection (CBP) Cargo Systems Messaging Service (CSMS) bulletins and emit one machine-readable change signal for each newly observed CSMS message that matches your monitor filters.

This Actor is designed for customs brokers, import/export operations, trade-compliance teams, logistics software, filing operations, and agents that need a persistent feed of operational CBP notices. It is not a customs ruling database, tariff calculator, legal-advice service, or substitute for controlling authorities.

What CSMS is

CBP uses CSMS to communicate operational and trade-processing information to users of automated cargo systems, including Automated Commercial Environment (ACE) changes, CATAIR/documentation updates, tariff-related notices, quota messages, broker/compliance information, outages, filing guidance, corrections, reminders, and other trade-system notices.

Official sources used by this Actor:

• CBP CSMS homepage
• official GovDelivery CSMS RSS surfaced by the CBP page
• individual official GovDelivery bulletins
• CBP CSMS archive as the official gap fallback

Production acquisition does not depend on search engines or third-party mirrors.

One CSMS message = one paid signal

The primary business event is:

NEW_CSMS_MESSAGE

A single new CSMS message produces at most one Dataset signal for one monitor. messageClass, topicTags, related CSMS numbers, relationships, and summary text are metadata on that same row; they are not separate paid events.

The stable source identity is the official CSMS message number. Message numbers are not assumed to be sequential.

Deterministic message classes

The Actor recognizes explicit source-native title prefixes:

• GUIDANCE
• UPDATED_GUIDANCE
• CORRECTION
• MANDATORY
• REMINDER
• UPDATE
• INFORMATION
• OTHER

OTHER is the fallback when no approved explicit prefix is present. These are deterministic routing labels, not legal interpretations.

Topic tags

The Actor can add deterministic tags when title/body text directly supports them:

• ACE_SYSTEM
• CATAIR_OR_SCHEMA
• HTS_UPDATE
• TRADE_REMEDY
• QUOTA
• BROKER_COMPLIANCE
• OUTAGE_OR_MAINTENANCE
• FORCED_LABOR
• PGA
• EXPORT_FILING
• IMPORT_FILING

A message can have multiple topic tags but still emits only one signal.

Related CSMS messages

The Actor extracts referenced CSMS numbers. When the bulletin explicitly uses language such as updates, corrects, replaces, supersedes, or follow-up, the Actor stores the corresponding structured relationship.

Allowed relationship values are:

UPDATES, CORRECTS, REPLACES, SUPERSEDES, FOLLOW_UP_TO, RELATED_TO.

The Actor does not infer a stronger relationship than the source text states.

First live run: baseline only

Each unique monitor starts independently.

On the first valid live run:

1. the Actor enumerates the official current CSMS window;
2. stores the accepted message identities for that monitor;
3. emits zero business signals.

Existing messages are not replayed as paid NEW_CSMS_MESSAGE events.

Later runs emit only newly observed messages that match that monitor.

Filter-specific monitor identity

Monitor state is isolated by a deterministic fingerprint of these normalized filters:

• messageClasses
• topicTags
• includeKeywords
• excludeKeywords

maxItems is intentionally excluded.

Changing filters creates a new monitor baseline and does not replay historical messages as paid changes for the old monitor. Changing only maxItems keeps the same monitor identity.

Pending queue and maxItems

maxItems caps Dataset output only.

If 80 new matching CSMS messages are discovered and maxItems is 30, the first 30 are emitted and the other 50 remain in the monitor's pending queue. On later runs, existing pending signals drain before newly created signals.

A successfully emitted signal is removed from pending state only after Dataset and OUTPUT persistence succeed and the accepted state is committed.

Source-gap safety

The normal current source is the official GovDelivery RSS surfaced by the CBP CSMS page.

The Actor stores the accepted current-window identities. If a later run has no overlap with the previously accepted source window, it resolves the official CBP archive PDF, maps its CSMS rows to the GovDelivery short links embedded by the official archive, follows only the approved lnks.gd -> content.govdelivery.com path, and verifies that the destination bulletin carries the same CSMS number before using it.

If the archive cannot prove continuity into the current source window, a row cannot be mapped, a redirect leaves the approved hosts, or the destination bulletin number does not match, the Actor fails closed:

SOURCE_GAP_ANOMALY

In that state:

• business signals = 0
• accepted monitor state remains unchanged
• the Actor does not silently skip an unknown interval

Rotation out of the current source window is never interpreted as a deletion, revocation, or legal-status change.

Input example

{
  "mode": "live",
  "messageClasses": ["GUIDANCE", "CORRECTION", "MANDATORY"],
  "topicTags": ["ACE_SYSTEM", "CATAIR_OR_SCHEMA"],
  "includeKeywords": ["cargo release"],
  "excludeKeywords": ["test environment"],
  "maxItems": 30
}

Filter lists use OR matching within a list. Different filter groups must all pass. Exclude keywords take precedence.

Output example

{
  "signalType": "NEW_CSMS_MESSAGE",
  "csmsNumber": "70000001",
  "messageClass": "GUIDANCE",
  "topicTags": ["ACE_SYSTEM", "IMPORT_FILING"],
  "title": "GUIDANCE: Example ACE filing clarification",
  "issuedAt": "2026-09-25T12:00:00.000Z",
  "issuedAtOriginal": "09/25/2026 08:00 AM EDT",
  "bulletinUrl": "https://content.govdelivery.com/accounts/USDHSCBP/bulletins/example",
  "relatedMessageNumbers": ["69999999"],
  "explicitRelationships": [
    { "type": "FOLLOW_UP_TO", "csmsNumber": "69999999" }
  ],
  "matchedFilters": ["messageClass:GUIDANCE", "topicTag:ACE_SYSTEM"],
  "summary": "Official CBP CSMS 70000001: GUIDANCE: Example ACE filing clarification",
  "sourcePublisher": "U.S. Customs and Border Protection",
  "sourceUrl": "https://www.cbp.gov/trade/automated/cargo-systems-messaging-service",
  "detectedAt": "2026-09-25T12:05:00.000Z"
}

The Actor does not persist full raw bulletin HTML in Dataset output.

Failure and state-commit safety

The accepted monitor state advances only after required acquisition/parsing succeeds and Dataset + OUTPUT persistence succeeds.

The run fails closed with no accepted-state mutation when, for example:

• official enumeration is empty;
• a required CSMS number or timestamp cannot be parsed;
• one CSMS number maps to conflicting bulletin URLs;
• a newly observed bulletin fails to fetch or parse;
• publisher/host validation fails;
• a source gap cannot be safely bridged.

Sample mode

mode: "sample" is deterministic and self-contained.

It uses three synthetic messages to demonstrate:

• GUIDANCE
• CORRECTION
• MANDATORY

The sample runs the production classification, topic-tag, relationship, filtering, monitor-fingerprint, and pending-queue logic.

Hard guarantees for sample mode:

• CBP HTTP requests: 0
• GovDelivery HTTP requests: 0
• production named KVS open/read/write: 0
• production snapshot updated: false

Legal reuse and attribution

Source attribution: U.S. Customs and Border Protection Cargo Systems Messaging Service (CSMS).

CBP-authored U.S. Government works are generally not protected by U.S. copyright under 17 U.S.C. § 105, subject to statutory exceptions and third-party rights. This Actor limits persisted/output content to source metadata, concise source-grounded summaries, and deterministic classifications needed for the product.

It does not redistribute third-party attachments or material carrying explicit third-party copyright merely because a CSMS bulletin links to it.

CBP/DHS seals and logos are not used. No endorsement, sponsorship, or association with CBP or DHS is implied.

Privacy

CSMS bulletins are institutional operational notices. V1 does not persist unnecessary individual contact names, direct phone numbers, or personal email addresses.

Important limitation / no legal advice

This Actor provides operational monitoring, not legal advice. It does not emit claims such as IMPORT_NOW_LEGAL, IMPORT_NOW_ILLEGAL, DUTY_INCREASED, DUTY_DECREASED, FILING_REQUIRED, RULING_REVOKED, or COMPLIANCE_VIOLATION.

Always consult the controlling statutes, regulations, Federal Register notices, CBP rulings, HTS material, official filing specifications, and other underlying authorities where applicable.

Scheduling

CBP does not guarantee a fixed publication cadence. Schedule the Actor at a frequency appropriate to your operations. The Actor is designed for recurring monitoring without making a fixed cadence promise.