Spranz Mail Flow - API Requirements
Purpose
This document describes all API endpoints and configurations needed from the Spranz ERP system to make the automated mail flow work. The n8n workflow processes incoming quote requests via email and generates quotations automatically.
Key features of the flow:
- Automatically reads incoming emails from a dedicated mailbox
- Uses AI (Claude) to analyze customer requests and match products
- Retrieves real-time stock and pricing information from Spranz ERP
- Generates professional quotations with correct pricing tiers
- Handles repeat orders by checking order history (no setup costs for returning customers)
- Escalates complex requests to human team members via WhatsApp
1. User/Customer Data
Why needed: When a customer sends an email requesting a quote, we need to identify who they are in the Spranz system. This allows us to apply the correct pricing, discounts, and credit terms automatically.
| Data Field | Description | Why Important |
|---|---|---|
| Customer Number | Unique ID in ERP | Links email to customer account |
| Company Name | Business name | For quotation header |
| Contact Person | Main contact | Personalized communication |
| Email address | Match incoming email to customer | |
| Phone | Phone number | For follow-up calls |
| Address | Billing/shipping | Shipping cost calculation |
| Discount Group | Customer tier | Apply correct pricing level |
| Credit Limit | Max order value | Flag large orders for review |
| Payment Terms | Net 30/60/etc | Include on quotation |
2. Product Data
Why needed: The AI needs to search and match products based on customer requests. Product details are shown in the quotation.
| Data Field | Why Important |
|---|---|
| SKU / Article Number | Unique product identifier for ordering |
| Product Name | Display name on quotation |
| Description | AI uses this to match customer requests |
| Category | Filter products by type |
| Available Colors | Match customer color preferences |
| Dimensions | Product specifications |
| Weight | Calculate shipping costs |
| Images URL | Include product images in quote |
| Min. Order Quantity | Validate customer quantities |
3. Stock/Inventory Data
Why needed: Before quoting, we need to verify the product is available. If not in stock, provide expected delivery date.
| Data Field | Why Important |
|---|---|
| Available Quantity | Can we fulfill the order? |
| Reserved Quantity | Already allocated to other orders |
| Expected Restock Date | When will new stock arrive? |
| Supplier Lead Time | How long to get from supplier? |
4. Pricing Data
Why needed: Promotional products use tiered pricing - the more you order, the lower the unit price. We need all price breaks to generate accurate quotes.
| Data Field | Why Important |
|---|---|
| Tiered Prices | Price per 100/250/500/1000/2500/5000 units |
| Customer-specific Discount | Special pricing for this customer |
| Print/Decoration Costs | Cost per color/technique |
| Setup Costs | One-time costs (screens, dies, etc.) |
| Shipping Rates | Per weight/destination zone |
5. Print/Decoration Techniques
Why needed: Different products support different printing methods. Each method has different costs, color limits, and positioning options.
| Data Field | Why Important |
|---|---|
| Available Techniques per Product | Screen print, pad print, laser, embroidery, etc. |
| Cost per Color | Additional cost for multi-color prints |
| Maximum Colors | How many colors possible per technique |
| Print Positions | Where on the product can be printed |
| Print Area Size | Maximum print dimensions |
6. Order History (Return Orders Check)
Why needed: For repeat orders, customers should NOT pay setup costs again. The system checks if this customer has ordered this product with the same print before.
| IMPORTANT: Return Order Logic | |
|---|---|
| Check Required | Has this customer ordered this SKU + same print technique + same artwork before? |
| If YES (repeat) | Waive setup costs, only charge unit price + print costs |
| If NO (new) | Include full setup costs in quotation |
Data needed for this check:
- Customer order history
- Previous order line items (SKU, technique, artwork reference)
- Order date (how recent was the last order?)
7. Quotation/Order Management
Why needed: After generating a quote, we need to save it in the ERP so sales can track it.
| Action | Description |
|---|---|
| Create Quotation | Start new quote with customer info |
| Add Quote Lines | Add products with qty, price, print options |
| Update Status | Draft → Sent → Accepted → Order |
| Convert to Order | When customer accepts the quote |
8. Track & Trace
Why needed: Customers can ask about their order status. The AI agent needs to look this up.
| Data Field | Description |
|---|---|
| Order Status | In production, Ready for shipping, Shipped, Delivered |
| Carrier | DHL, UPS, PostNL, etc. |
| Tracking Number | For customer to track shipment |
| Expected Delivery Date | When will it arrive? |
9. Sample Orders
Why needed: Customers often want to see/feel a product before ordering. The system handles sample requests.
| Data Field | Description |
|---|---|
| Sample Policy | Free, paid, or limited per customer? |
| Sample Limit | Max samples per customer per month |
| Sample Cost | If charged, what is the cost? |
Required API Endpoints (17 Total)
These are the endpoints we need from the Spranz ERP. Please provide the URLs and authentication method.
| Nr | Endpoint | Method | URL from Spranz |
|---|---|---|---|
| 1 | Get Customer (by number or email) | GET | |
| 2 | Search Products | GET | |
| 3 | Get Product Details | GET | |
| 4 | Check Stock Availability | GET | |
| 5 | Get Tiered Pricing | GET | |
| 6 | Get Print Techniques per Product | GET | |
| 7 | Create Quotation | POST | |
| 8 | Get Order Status / Track Trace | GET | |
| 9 | Request Sample | POST | |
| 10 | Create Stock Reservation | POST | |
| 11 | API Authentication | POST | |
| 12 | Get Customer Order History | GET | |
| 13 | Get Invoices | GET | |
| 14 | Get Business Hours | GET | |
| 15 | Submit Discount Request | POST | |
| 16 | WhatsApp Notification | POST | |
| 17 | Check Return Orders (no setup costs) | GET |
Yellow fields: fill in URLs from Spranz after the meeting
Email Configuration
The n8n workflow needs to read incoming emails. We need access credentials for the mailbox.
Option A: Microsoft 365 / Outlook (Recommended)
For Microsoft 365, we need an Azure App Registration with Mail.Read and Mail.Send permissions.
| Setting | Value |
|---|---|
| Mailbox Address | e.g. quotes@spranz.de |
| Azure App (Client) ID | |
| Azure Tenant ID | |
| Client Secret |
Option B: IMAP/SMTP
If not using Microsoft 365, provide standard IMAP/SMTP credentials.
| Setting | Value |
|---|---|
| IMAP Server | |
| IMAP Port | 993 (SSL) |
| SMTP Server | |
| SMTP Port | 587 (TLS) |
| Username | |
| Password / App Password |
Required Mailbox Folders
These folders should exist in the mailbox. The workflow will move emails between them.
| Folder | Purpose |
|---|---|
| Inbox | New quote requests arrive here |
| Quotation Done | Successfully processed - quote sent |
| Awaiting Response | Waiting for customer reply (clarification needed) |
| Team Escalation | Complex requests forwarded to human team |
n8n Workflow Location
Internal URL: http://192.168.1.26:8090/workflow/SpranzMailFlow02
Workflow ID: SpranzMailFlow02
Total nodes: 113