Quickstart

Copied
Previous Next

This quickstart will walk you through the minimal path to receiving your first webhook from Sema.

Use an SDK

For production integrations, use our official Python or Node.js SDKs. They handle authentication, types, and webhook verification for you.

Prerequisites

  • API key: Get one in the Sema dashboard under API keys (create one for development or production). Use sk_test_... for development and sk_live_... for production. Never commit keys - use environment variables or a secrets manager.
  • Base URL: https://dev-api.withsema.com for production; use SEMA_BASE_URL for local or testing overrides.
  • A webhook endpoint you control (must return 2xx quickly). For local development with cloud Sema, expose your server with a tunnel (e.g. ngrok: ngrok http 8080) and use the https://...ngrok.io/your-path URL as webhook_url.

1) Create an Inbox

Set SEMA_BASE_URL=https://dev-api.withsema.com and SEMA_API_KEY to your key, then run:

curl -X POST "$SEMA_BASE_URL/v1/inboxes" \
  -H "Authorization: Bearer $SEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Inbox",
    "webhook_url": "https://example.com/sema/webhooks",
    "webhook_secret": "whsec_<your_secret>"
  }'

Save the returned id as INBOX_ID.

2) Submit an Item (multipart upload)

curl -X POST "$SEMA_BASE_URL/v1/inboxes/$INBOX_ID/items" \
  -H "Authorization: Bearer $SEMA_API_KEY" \
  -F "file=@./sample.txt" \
  -F "sender_address=sender@example.com" \
  -F "subject=Hello from Sema" \
  -F "provider_message_id=demo-001"

3) Receive the Webhook

Sema will POST an ITEM_READY webhook to your webhook_url with Standard Webhooks headers:

  • webhook-id
  • webhook-timestamp
  • webhook-signature

The request body is a versioned envelope. See API Reference → Webhooks.

Next steps

Home Why Sema