An Inbox is the core integration unit in Sema.

Think of it as a secure “mailbox with superpowers”: it can receive content from multiple channels, apply sender policies, store raw bytes durably, normalize the content, and reliably deliver an event to your system via webhooks.

What an Inbox does¶

At a high level, an inbox:

1. Receives content from API uploads and email (inbox addresses at your configured domain, e.g. support@in.withsema.com, or your custom domain)
2. Authorizes senders (allowlists by email and/or domain, plus other policy modes)
3. Stores raw content durably before heavy processing
4. Triggers pipeline processing (parse/normalize/enrich depending on configuration)
5. Delivers to your webhook with cryptographic signing and retries

Inbox lifecycle¶

Create Inbox
    ↓
Configure (webhook URL, sender rules, etc.)
    ↓
Activate (is_active: true)
    ↓
Receive Items → Pipeline Processing → Webhook Delivery
    ↓
Deactivate (optional)
    ↓
Delete (permanent)

Inbox vs Item (mental model)¶

• Inbox: configuration + policy boundary. It describes how content should be accepted and delivered.
• Item: a single unit of received content. Items flow through the pipeline (received → ready → delivered).

When you integrate with Sema, you typically:

1. Create an inbox (once)
2. Submit items into that inbox (many times)
3. Receive webhooks when items are ready

Sender authorization¶

Inboxes can restrict who is allowed to submit content. You configure this with two optional allowlists on the inbox:

• allowed_senders — exact email addresses (e.g. ["partner@external.com"])
• allowed_domains — domains; any address whose part after @ matches is allowed (e.g. ["company.com"])

Set these when creating an inbox (POST /v1/inboxes) or when updating one (PATCH /v1/inboxes/{inbox_id}). Matching is case-insensitive.

Behavior:

• If both lists are empty, the inbox accepts all senders.
• If either list has values, a sender must match at least one: either their full address is in allowed_senders, or their domain (the part after @) is in allowed_domains.

If a submission comes from a sender that doesn’t match, the request is rejected with HTTP 403 and no item is created — the denial is not stored. See API Reference for request/response schemas.

Webhook delivery (high level)¶

Inboxes deliver events to your webhook endpoint when an item is ready:

• Requests are signed (so you can verify authenticity)
• Failures are retried automatically (so you don’t need to poll)
• Payloads can be thin (refs + IDs) or full (include rich deliverable data), depending on the inbox configuration

The detailed spec (headers, signature verification, retry behavior) will live in API Reference → Webhooks.