- The most sophisticated import portal is useless if suppliers keep sending catalogue and inventory files by email.
- That is not necessarily resistance to technology.
- The client problem was therefore not “how do we eliminate email?” It was “how do we preserve that familiar entry point without letting an attachment behave like a trusted database command?”
- On a B2B marketplace built with Medusa, we created an email-to-import capability for supplier catalogues, catalogue updates and inventory.
The client problem
The most sophisticated import portal is useless if suppliers keep sending catalogue and inventory files by email.
That is not necessarily resistance to technology. Email may already be part of the supplier's daily workflow. Their ERP exports a file, an operator attaches it and a known recipient confirms that it arrived. Asking every supplier to learn another interface can move friction outside the platform without improving the data.
The client problem was therefore not “how do we eliminate email?” It was “how do we preserve that familiar entry point without letting an attachment behave like a trusted database command?”
On a B2B marketplace built with Medusa, we created an email-to-import capability for supplier catalogues, catalogue updates and inventory. The platform identifies an authorised sender for a specific seller and file type, stores the attachment, applies the seller's mapping, creates a durable import session and runs the same tracked workflows used by controlled uploads.
Email remains the delivery channel. Medusa becomes the system that decides what the file is allowed to do.
Treat the inbox as an intake desk, not an API
An email attachment can contain useful business data, but the message itself proves very little.
It does not automatically prove which supplier the file belongs to. It does not say whether the attachment is a catalogue, a delta, an inventory snapshot or an invoice. It does not define column meanings, units or import policy. It certainly should not acquire authority merely because it reached the correct mailbox.
We modelled inbound email as an intake record. The message and its stored attachments receive an identity, seller context, feature, status and validation history before any commerce workflow starts.
This creates a deliberate gap between receipt and execution. A file can be received but not ready. It can be ambiguous, unsupported or missing configuration. It can fail preprocessing without half-updating the catalogue.
That gap is the control plane. The inbox accepts a package; the application establishes whether that package is admissible and which workflow may consume it.
Authorise the sender for one seller and one feature
A supplier may use different people or automated systems for different files. The address authorised to send invoices may not be authorised to update catalogue content. A shared service provider may send files for several sellers.
The platform stores authorised sender records by seller, feature and normalised email address. Catalogue, inventory, updates and invoice intake are separate capabilities that can be enabled independently.
This prevents a broad rule such as “anything from this domain belongs to supplier X.” It also avoids assuming that one approved email address should be able to perform every supplier operation.
If an address can map to more than one seller, the routing logic does not guess. Ambiguity remains administrative work rather than becoming an accidental cross-seller import.
Feature-scoped authorisation gives a simple business answer: this sender may submit this kind of file for this supplier. It is the first boundary, not the last one.
Require a seller-specific interpretation before importing
Two suppliers can send equally valid spreadsheets with completely different shapes.
One calls its key SKU; another uses ITEM. Inventory may be expressed as one quantity column per warehouse or as location rows. Prices may arrive in cents. A catalogue update may contain only a few mapped fields. Excel files may need conversion before the streaming CSV workflow can read them.
The email-ingest settings connect each seller and feature to an explicit interpretation.
Catalogue files use an assigned catalogue preset. Inventory uses an inventory preset or a defined column map. Catalogue updates use a per-vendor field map that identifies the SKU and the fields the delta may overwrite. Optional file-processing settings describe how to prepare inventory and update attachments.
If the required mapping is absent, the import does not fall back to wishful column guessing. It stops with an actionable configuration error.
That failure is valuable. A file is not safe because its headers look familiar. The platform must know how this supplier's business vocabulary maps to Medusa before it changes commerce data.
Store the attachment before starting work
The import workflow runs from a stored file reference rather than treating the email body as the only record of what arrived.
The inbound record keeps attachment identifiers and the original filename. When preprocessing is required, the platform creates a prepared private file and records the transformation metadata. It then mints an upload session pointing to the exact file the import will consume.
The upload session carries the seller, purpose, provider reference and email-ingest context. It also preserves the mapping or policy snapshot used for this run.
This solves an important support question: which bytes and which configuration produced this import?
Without a durable file and session, retry can mean “run today's configuration against an attachment we can no longer identify.” With them, the platform has a stable bridge from inbound message to import execution.
Claim the ready record exactly once
Email processing is event-driven. A subscriber may retry after an error. An operator may also press “continue import” while background automation is starting. Both paths can observe the same ready attachment.
Before creating an import, the platform atomically changes the inbound record from ready to importing. The update succeeds only when the record is still ready.
If another worker already claimed it, the second caller receives a conflict with the current status. It does not create another product or inventory import.
This is a narrow but essential concurrency guarantee. It does not claim that every external email is delivered exactly once. It ensures that one admitted inbound record cannot casually fan out into duplicate import starts.
The record status becomes an operational lock expressed in the same language the support team sees.
Run email files through the real import workflows
We did not create a lightweight “email importer” with different rules from the portal.
After admission and preparation, catalogue and catalogue-update files enter the existing CSV-to-products workflow. Inventory files enter the tracked bulk inventory workflow. Each receives a durable import record, upload session, transaction identity and status URL.
For catalogue updates, the workflow also receives the explicit update route, delimiter and field-policy snapshot. Existing SKUs can be updated within that policy; unknown SKUs are parked for review rather than created.
For inventory, the import records the selected replace or add mode. Replace is the default for an emailed inventory source unless the caller explicitly requests addition.
Reusing the real workflows matters. Progress, validation, row states, cancellation behaviour and downstream synchronisation should not depend on whether a supplier dragged the file into a browser or attached it to an email.
Email changes the entrance. It does not create a lower-governance path through the catalogue.
Keep private supplier files out of unnecessary AI processing
Some supplier files are irregular enough to benefit from analysis, but automatic ingestion should not casually send private commercial data to an external model.
For the update path, runtime parsing uses the saved vendor field map. A deterministic analyser reads a small backend sample to identify delimiter and free-text-column structure. Automatic update imports explicitly avoid sending the private file to OpenAI.
This also improves predictability. The meaning of SKU, price and description comes from an administrator-approved mapping, not from a fresh model interpretation on every email.
AI can still help an operator establish a mapping in a controlled setup flow. Once the contract exists, recurring automation should favour that durable decision.
The principle is broader than email: use intelligence to reduce configuration work, but do not let probabilistic interpretation silently redefine a financial or catalogue contract at runtime.
Do not let inventory overtake its catalogue
Suppliers often send a catalogue file and an inventory file as a pair.
Inventory refers to products through SKUs. If the inventory workflow runs before the corresponding catalogue has created or validated those products, rows fail or appear to be missing. A simple delay—“wait five minutes before processing inventory”—cannot solve the problem reliably. Catalogue duration changes with file size, load and review state.
We built a durable email-ingest run that can link one supplier's catalogue attachment with its inventory attachment. Catalogue states such as received, ready and importing explicitly block the paired inventory. When the inventory arrives, the system links it to the oldest compatible open catalogue run instead of relying on arrival timing alone.
After the catalogue reaches its terminal imported state, queued inventory records can be emitted for processing. If catalogue validation or import fails, the linked inventory receives the blocking reason instead of proceeding against an incomplete product set.
The dependency is business state, not elapsed time: inventory waits until the catalogue it depends on is ready.
Make failure visible in the same journey
Automation becomes expensive when failure disappears into logs.
The inbound record can carry ready, importing, failed and imported context. Catalogue and inventory run records preserve their own identifiers, upload sessions and failure reasons. Starting a workflow updates progress metadata. A failed catalogue can mark the run and its linked inventory with a useful reason.
The seller-facing flow can return a status URL for the actual product or inventory import. The administrative Control Center can surface failed email ingestion and pending catalogue decisions alongside other operational work.
This gives support a connected story:
- which email and attachment were admitted;
- which seller and feature they matched;
- which preset or field map was used;
- which import record and session were created;
- whether another import was already active;
- why the workflow stopped;
- whether inventory is waiting for catalogue completion.
The system does not merely say “we received your email.” It can explain what happened next.
Separate catalogue, delta, inventory and invoice behaviour
A single uploads mailbox can hide four very different business capabilities.
A full catalogue may create products after validation. A catalogue delta may only update authorised fields on existing seller SKUs and park new ones. An inventory file changes quantities under an add or replace policy. An invoice attachment is stored for financial review and is not sent into the product-import pipeline.
The intake model keeps those features explicit. An invoice record is rejected if somebody attempts to start it as a catalogue import. Inventory checks whether another inventory run is already pending or processing. Catalogue and update routes require their own mappings.
This prevents convenience from flattening domain rules. “It came by email” is not a workflow type.
The attachment must enter the capability that understands its business meaning.
Why Medusa was the right foundation
Medusa supplied the product, inventory and workflow foundations. The client needed a supplier operating model around them.
We extended the platform with inbound-email records, feature-scoped senders, seller ingest settings, private file preparation, upload sessions and durable catalogue/inventory coordination. Once a file is admitted, it enters the same Medusa workflows used elsewhere in the product.
That is the value of an extensible commerce engine. We did not ask suppliers to reshape their organisation around a generic uploader, and we did not bypass the commerce platform with mailbox scripts. We brought the familiar supplier interaction into a controlled domain workflow.
The architecture serves both sides: suppliers keep a low-friction submission method, while the marketplace retains identity, policy, sequencing and operability.
A practical email-to-import checklist
Before connecting an inbox to commerce automation, define these contracts:
- Which email address receives each feature?
- Which senders are authorised for which seller and file type?
- What happens when sender routing is ambiguous?
- Is each feature independently enabled?
- Which preset or field map interprets the supplier's columns?
- Does missing configuration block the run clearly?
- Where is the original or prepared attachment stored?
- Which configuration snapshot travels with the upload session?
- Can one ready record be claimed by only one import start?
- Does email reuse the same tracked workflows as manual upload?
- Are private files excluded from unnecessary external AI processing?
- How are catalogue and inventory attachments paired?
- Does inventory wait on a durable catalogue state rather than a timer?
- What happens to inventory when the paired catalogue fails?
- Can operators trace the message, file, session, import and failure reason?
If those answers live only in mailbox conventions, the integration is fragile. If they live in the platform, email can become a dependable supplier channel.
The broader lesson
The client did not need to choose between supplier convenience and platform control.
They needed a boundary between the two.
We kept email as the familiar submission surface, then made Medusa establish seller identity, feature authority, file interpretation, workflow state and dependency order. An attachment becomes an import only after it passes those gates. Catalogue, updates, inventory and invoices keep their own rules. Inventory cannot race ahead of the catalogue it references.
For suppliers, the workflow still begins with attaching a file. For the marketplace, it becomes authenticated, traceable commerce operations.
That is the useful form of automation: fit the way partners already work, without allowing convenience to bypass the controls the business needs.