Structured Data Extraction

Business Define a JSON schema on your inbox. When an email arrives, an LLM extracts the fields you specified and returns them as structured data in the message and webhook payload. No parsing or regex needed.

How it works

Inbound email → Commune parses content → LLM extracts against your schema → extracted_data in message & webhook

You define a JSON schema on your inbox describing what to extract
When an email arrives, Commune uses an LLM to extract data matching your schema
The extracted data appears in message.metadata.extracted_data and webhook.extractedData
Your agent uses the structured data directly — no parsing or regex needed

Configure extraction schema

Set a schema on your inbox to define what data to extract:

await commune.inboxes.setExtractionSchema({
  domainId: 'domain_id',
  inboxId: 'inbox_id',
  schema: {
    name: 'support_ticket',
    description: 'Extract support ticket details from customer emails',
    enabled: true,
    schema: {
      type: 'object',
      properties: {
        order_number: {
          type: 'string',
          description: 'Order or reference number mentioned in the email',
        },
        intent: {
          type: 'string',
          enum: ['billing', 'technical', 'shipping', 'returns', 'general'],
          description: 'Primary customer intent',
        },
        urgency: {
          type: 'string',
          enum: ['low', 'medium', 'high', 'critical'],
          description: 'How urgent the request appears',
        },
        summary: {
          type: 'string',
          description: 'One-sentence summary of the customer request',
        },
        sentiment: {
          type: 'string',
          enum: ['positive', 'neutral', 'negative', 'angry'],
          description: 'Customer emotional tone',
        },
      },
    },
  },
});

client.inboxes.set_extraction_schema(
    domain_id=domain_id,
    inbox_id=inbox_id,
    name="support_ticket",
    description="Extract support ticket details from customer emails",
    enabled=True,
    schema={
        "type": "object",
        "properties": {
            "order_number": {
                "type": "string",
                "description": "Order or reference number",
            },
            "intent": {
                "type": "string",
                "enum": ["billing", "technical", "shipping", "returns", "general"],
            },
            "urgency": {
                "type": "string",
                "enum": ["low", "medium", "high", "critical"],
            },
            "summary": {"type": "string"},
            "sentiment": {
                "type": "string",
                "enum": ["positive", "neutral", "negative", "angry"],
            },
        },
    },
)

curl -X PUT "https://api.commune.email/v1/domains/DOMAIN_ID/inboxes/INBOX_ID/extraction-schema" \
  -H "Authorization: Bearer comm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support_ticket",
    "description": "Extract support ticket details",
    "enabled": true,
    "schema": {
      "type": "object",
      "properties": {
        "order_number": { "type": "string", "description": "Order number" },
        "intent": { "type": "string", "enum": ["billing", "technical", "shipping"] },
        "urgency": { "type": "string", "enum": ["low", "medium", "high"] },
        "summary": { "type": "string" },
        "sentiment": { "type": "string", "enum": ["positive", "neutral", "negative"] }
      }
    }
  }'

Schema parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	Schema name for identification
`description`	`string`	No	What this schema extracts (helps the LLM)
`enabled`	`boolean`	No	Toggle extraction on/off (default: true)
`schema`	`object`	Yes	JSON Schema defining the fields to extract

Schema definition tips

Use description on every property — the LLM uses these to understand what to look for
Use enum for categorical fields — constrains output to valid values
Keep schemas focused — extract 3–8 fields per schema for best accuracy
Use type: "string" for dates — the LLM returns ISO strings; parse in your code

Example: extracted data in webhook

When a customer sends:

“Hi, my order #ORD-5678 hasn’t arrived yet. I ordered it 3 days ago and the tracking still shows ‘processing’. This is really frustrating. Can you please look into this urgently?”

Your webhook receives:

{
  "message": {
    "content": "Hi, my order #ORD-5678 hasn't arrived yet...",
    "metadata": {
      "subject": "Order not received",
      "extracted_data": {
        "order_number": "ORD-5678",
        "intent": "shipping",
        "urgency": "high",
        "summary": "Customer's order ORD-5678 hasn't arrived after 3 days, tracking shows processing",
        "sentiment": "negative"
      }
    }
  },
  "extractedData": {
    "order_number": "ORD-5678",
    "intent": "shipping",
    "urgency": "high",
    "summary": "Customer's order ORD-5678 hasn't arrived after 3 days, tracking shows processing",
    "sentiment": "negative"
  }
}

Your agent can now route this directly — look up order ORD-5678, check shipping status, and send a targeted response, all without parsing the email text.

Use case examples

E-commerce support

{
  "schema": {
    "type": "object",
    "properties": {
      "order_number": { "type": "string", "description": "Order ID or number" },
      "product_name": { "type": "string", "description": "Product mentioned" },
      "issue_type": {
        "type": "string",
        "enum": ["damaged", "wrong_item", "not_received", "return", "refund"]
      },
      "amount": { "type": "string", "description": "Dollar amount if mentioned" }
    }
  }
}

SaaS onboarding

{
  "schema": {
    "type": "object",
    "properties": {
      "company_name": { "type": "string", "description": "Company or org name" },
      "company_size": { "type": "string", "description": "Number of employees or team size" },
      "use_case": { "type": "string", "description": "What they want to use the product for" },
      "integration_needs": {
        "type": "string",
        "description": "Integrations or tools they need"
      },
      "timeline": { "type": "string", "description": "When they need to be up and running" }
    }
  }
}

Invoice processing

{
  "schema": {
    "type": "object",
    "properties": {
      "invoice_number": { "type": "string" },
      "vendor_name": { "type": "string" },
      "total_amount": { "type": "string", "description": "Total amount with currency" },
      "due_date": { "type": "string", "description": "Payment due date (ISO format)" },
      "line_items": {
        "type": "string",
        "description": "Comma-separated list of line items"
      }
    }
  }
}

Disable extraction

await commune.inboxes.removeExtractionSchema({
  domainId: 'domain_id',
  inboxId: 'inbox_id',
});

curl -X DELETE "https://api.commune.email/v1/domains/DOMAIN_ID/inboxes/INBOX_ID/extraction-schema" \
  -H "Authorization: Bearer comm_..."

client.inboxes.remove_extraction_schema(
    domain_id=domain_id,
    inbox_id=inbox_id,
)

Configure structured extraction on an inbox via MCP

Open in Cursor

Extraction object on inbox

When an extraction schema is configured, the inbox object includes:

{
  "extractionSchema": {
    "name": "support_ticket",
    "description": "Extract support ticket details",
    "schema": { ... },
    "enabled": true
  }
}

Structured extraction is a paid feature available on Pro plans and above.

What’s next?

Webhooks

Access extracted data in the webhook payload on every inbound email.

Inboxes

Configure extraction schemas on individual inboxes.

Prompt Injection Detection

Protect your agent from adversarial content in inbound emails.

Search

Search threads by semantic meaning using extracted data.

Get Started

SDKs

Email

Commune OAuth

Phone & SMS

Security

Integrations

Examples

Community

Structured Data Extraction

How it works

Configure extraction schema

Schema parameters

Schema definition tips

Example: extracted data in webhook

Use case examples

E-commerce support

SaaS onboarding

Invoice processing

Disable extraction

Extraction object on inbox

What’s next?

Webhooks

Inboxes

Prompt Injection Detection

Search

​How it works

​Configure extraction schema

​Schema parameters

​Schema definition tips

​Example: extracted data in webhook

​Use case examples

​E-commerce support

​SaaS onboarding

​Invoice processing

​Disable extraction

​Extraction object on inbox

​What’s next?

Webhooks

Inboxes

Prompt Injection Detection

Search

How it works

Configure extraction schema

Schema parameters

Schema definition tips

Example: extracted data in webhook

Use case examples

E-commerce support

SaaS onboarding

Invoice processing

Disable extraction

Extraction object on inbox

What’s next?