Webhooks Overview

Webhooks are the best way to get real-time information about what’s happening with your emails. Instead of constantly asking the PostNuvia API if there’s a new email (a process called polling), you can register a URL, and we will send you a POST request with the details as soon as an event happens.

This event-driven approach is more efficient and allows you to build fast, responsive agents that can react instantly to incoming messages.

Why Use Webhooks?

• Real-Time Speed: Build conversational agents that can reply to incoming emails in seconds.
• Efficiency: Eliminates the need for constant polling, which saves you computational resources and simplifies your application logic.

Available Events

PostNuvia supports sixteen webhook event types. When creating a webhook, you can subscribe to specific events or receive all standard events. See Webhook Events for full payload details.

Message events:

• message.received — New email received and processed in one of your inboxes
• message.received.spam — A message was received and classified as spam (requires label_spam_read permission)
• message.received.blocked — A message was received and matched a block list entry (requires label_blocked_read permission)
• message.received.unauthenticated — A message was received without authentication headers, so PostNuvia could not verify whether it was authenticated
• message.sent — Message successfully sent from your inbox
• message.delivered — Delivery confirmed by the recipient’s mail server
• message.bounced — Message failed to deliver and bounced back
• message.complained — Recipient marked your message as spam
• message.rejected — Message rejected before send (validation or policy)

Domain events:

• domain.verified — Custom domain successfully verified

Calendar events (require calendar_event_read; see Calendar Webhooks):

• calendar.event.created — A calendar event was created, or a date of a recurring event was edited for the first time
• calendar.event.updated — A calendar event, or one or more dates of a recurring event, changed or were cancelled
• calendar.event.deleted — A one-off or recurring calendar event was deleted
• calendar.event.responded — An attendee’s response to an invitation changed
• calendar.event.starting — A calendar event, or one date of a recurring event, started
• calendar.event.ending — A calendar event, or one date of a recurring event, ended

Updating event_types on a webhook

When you update a webhook, you can change which events it receives by sending event_types on PATCH:

• Non-empty array: Replaces the webhook’s subscribed event types in full (same idea as create: you set the whole list, not a diff). If you send only one type, the webhook will only receive that type afterward.
• Omitted or empty array: Leaves the current event types unchanged. You cannot clear all subscriptions by sending an empty list.

Subscribing to message.received.spam, message.received.blocked, or message.received.unauthenticated on update still requires the same label permissions as on create.

Custom delivery headers

Add custom HTTP headers when you create a webhook to authenticate PostNuvia deliveries with your endpoint or pass routing metadata. The values are write-only: PostNuvia sends them with each delivery but never returns them in a webhook response.

Use get_headers to list the configured header names without exposing their values. Use the separate update_headers method to rotate values, add keys, and remove keys atomically. An update must set at least one header or name at least one header to remove, and the same header cannot appear in both operations regardless of casing.

webhook = client.webhooks.create(
    url="https://your-server.com/webhooks",
    event_types=["message.received"],
    headers={"Authorization": "Bearer hook-secret", "X-Environment": "production"},
)
configured = client.webhooks.get_headers(webhook.webhook_id)
client.webhooks.update_headers(
    webhook.webhook_id,
    headers={"Authorization": "Bearer rotated-secret"},
    remove_headers=["X-Environment"],
)

The same headers create field and get_headers / update_headers methods are available under pods.webhooks and inboxes.webhooks. Store header values in a secret manager and rotate them with update_headers; retrieving the configured names cannot recover a lost value.

Scoping a webhook to a pod or inbox

By default a webhook is registered at the organization level. You can limit it to a pod or inbox in two ways. Both receive the same events; they differ in who owns the webhook:

• From the organization endpoint: pass pod_ids or inbox_ids when you webhooks.create (and add or remove them later with add_pod_ids / add_inbox_ids on update). The webhook still belongs to the organization, so pod- and inbox-scoped API keys cannot see or change it. Use this when one webhook should cover several pods, or when the pod’s own users should not manage it.
• From the scoped endpoints: call pods.webhooks.create(pod_id, ...) or inboxes.webhooks.create(inbox_id, ...). The pod or inbox comes from the path, so you don’t pass pod_ids / inbox_ids in the body. A pod-scoped webhook receives events for the whole pod (optionally narrowed to specific inboxes with inbox_ids); an inbox-scoped webhook is fixed to that inbox and can only change its event_types. The webhook belongs to that pod or inbox.

The scoped endpoints are the natural fit for pod- or inbox-scoped API keys: such a key can manage only its own webhooks, and a scoped webhook must always keep at least one pod or inbox subscription.

A webhook receives an event that matches any of its pods or inboxes. A pod covers every inbox in it, so adding one of that pod’s inboxes does not narrow the webhook. To receive only specific inboxes, create the webhook with inbox_ids and no pod.

# webhook scoped to a single pod
client.pods.webhooks.create(
    pod_id="pod_abc123",
    url="https://your-server.com/webhooks",
    event_types=["message.received"],
)
# webhook scoped to a single inbox
client.inboxes.webhooks.create(
    inbox_id="agent@domain.com",
    url="https://your-server.com/webhooks",
    event_types=["message.received"],
)

The Webhook Workflow

The process is straightforward:

client.webhooks.create(
    url="https://<your-ngrok-url>.ngrok-free.app/webhooks",
    event_types=["message.received", "message.sent"],
)

Payload Structure

When PostNuvia sends a webhook, the payload includes event_type and event_id, plus event-specific data. The example below shows a message.received payload; other events use different top-level objects (send, delivery, bounce, etc.). See Webhook Events for each event’s payload shape.

Payload size limit

Webhook payloads are capped at 1 MB. When a message exceeds this limit, PostNuvia omits the text and html fields from the webhook payload to reduce size. All other metadata is still included. Inline images embedded in the HTML (such as base64-encoded data URIs) count toward the payload size and are a common reason for the limit being reached.

Omitted content is always available through the API. After receiving a webhook, fetch the full message to access the complete body and attachment data:

# fetch the full message after receiving a webhook
message = client.inboxes.messages.get(
    inbox_id=payload["message"]["inbox_id"],
    message_id=payload["message"]["message_id"],
)
text_body = message.text
html_body = message.html

{
  "event_type": "message.received",
  "event_id": "evt_123abc...",
  "message": {
    "from_": ["sender@example.com"],
    "organization_id": "org_abc123...",
    "inbox_id": "inbox_def456...",
    "thread_id": "thd_ghi789...",
    "message_id": "<jkl012@postnuvia.com>",
    "labels": ["received"],
    "timestamp": "2023-10-27T10:00:00Z",
    "reply_to": ["reply-to@example.com"],
    "to": ["recipient@example.com"],
    "cc": ["cc-recipient@example.com"],
    "bcc": ["bcc-recipient@example.com"],
    "subject": "Email Subject",
    "preview": "A short preview of the email text...",
    "text": "The full text body of the email.",
    "html": "<html>...</html>",
    "attachments": [
      {
        "attachment_id": "att_pqr678...",
        "filename": "document.pdf",
        "content_type": "application/pdf",
        "size": 123456,
        "inline": false
      }
    ],
    "in_reply_to": "<parent456@postnuvia.com>",
    "references": ["<ref001@postnuvia.com>", "<ref002@postnuvia.com>"],
    "sort_key": "some-sort-key",
    "updated_at": "2023-10-27T10:00:05Z",
    "created_at": "2023-10-27T10:00:00Z"
  }
}

Field Descriptions

• event_type (string): The event type (e.g. message.received, message.sent, message.delivered). Payload structure varies by event—see Webhook Events for each event’s shape.
• event_id (string): A unique identifier for this specific event delivery.
• message (object): A dictionary containing the full details of the received email message.
  • from_ (array<string>): The sender’s email address. Note the trailing underscore to avoid conflict with the Python keyword.
  • organization_id (string): The ID of your organization.
  • inbox_id (string): The ID of the inbox that received the message.
  • thread_id (string): The ID of the conversation thread.
  • message_id (string): The unique ID of this specific message.
  • labels (array<string>): Labels associated with the message (e.g., received, sent).
  • subject (string): The subject line of the email.
  • preview (string): A short plain-text preview of the email body.
  • text (string): The plain-text body of the email. May be omitted when the webhook payload exceeds the 1 MB size limit. Fetch the full message via the API if this field is missing.
  • html (string): The HTML body of the email, if present. May be omitted when the webhook payload exceeds the 1 MB size limit. Fetch the full message via the API if this field is missing.
  • attachments (array<object>): A list of attachment metadata, each with its own attachment_id, filename, content_type, size, and inline status. Attachment content is not included in the webhook payload; download attachments through the API.
  • in_reply_to (string): The message_id of the email this message is a reply to, if applicable.

Copy for Cursor / Claude

Copy one of the blocks below into Cursor or Claude for complete Webhooks API knowledge in one shot.

"""
PostNuvia Webhooks — copy into Cursor/Claude.
Setup: pip install postnuvia python-dotenv. Set POSTNUVIA_API_KEY in .env.
Return 200 immediately; process payload in background.
API reference:
- webhooks.create(url, event_types?, inbox_ids?, pod_ids?, client_id?, headers?)
- webhooks.get(webhook_id), webhooks.get_headers(webhook_id), webhooks.list(limit?, page_token?)
- webhooks.update(webhook_id, add_inbox_ids?, remove_inbox_ids?, add_pod_ids?, remove_pod_ids?, event_types?)
- webhooks.update_headers(webhook_id, headers?, remove_headers?)
- webhooks.delete(webhook_id)
- scoped variants: pods.webhooks.* (pod_id) and inboxes.webhooks.* (inbox_id) — same CRUD, scope from the path
Events: message.received, message.received.spam, message.received.blocked, message.received.unauthenticated, message.sent, message.delivered, message.bounced, message.complained, message.rejected, domain.verified, calendar.event.created, calendar.event.updated, calendar.event.deleted, calendar.event.responded, calendar.event.starting, calendar.event.ending (calendar events need calendar_event_read)
Payload: event_type, event_id, plus message/send/delivery/bounce/complaint/reject/domain; calendar.event.* carry inbox_id and calendar_event. Verify with Svix (webhook.secret).
Custom delivery header values are write-only. get_headers returns names only; update_headers rotates or removes them.
Note: message.received.spam, message.received.blocked, and message.received.unauthenticated are excluded by default. To receive them, explicitly include them in event_types and ensure the API key has label_spam_read / label_blocked_read permissions for spam and blocked events.
On update, non-empty event_types replaces the subscribed list in full (omit or [] to leave types unchanged).
"""
import os
from dotenv import load_dotenv
from postnuvia import PostNuvia
load_dotenv()
client = PostNuvia(api_key=os.getenv("POSTNUVIA_API_KEY"))
wh = client.webhooks.create(url="https://your-server.com/webhooks", event_types=["message.received"], client_id="my-webhook-v1")
all_wh = client.webhooks.list()
secret = client.webhooks.get(wh.webhook_id).secret

Next Steps