Receiving Emails & Webhooks
Relevant source files
The following files were used as context for generating this wiki page:
The Resend Python SDK provides comprehensive tools for managing real-time event notifications through webhooks and retrieving inbound email data. Webhooks enable your application to react to events like email delivery, clicks, and bounces, while the Receiving API allows for the direct retrieval of inbound email content and attachments.
The system consists of two primary modules: the Webhooks class for managing endpoints and verifying incoming signatures, and the Emails.Receiving submodule for accessing inbound messages.
Webhook Management
The Webhooks module manages the lifecycle of webhook endpoints and allows you to monitor the delivery of events to those endpoints. You configure webhooks to send HTTP POST requests to your server when specific events occur in the Resend platform.
Core Operations
The SDK supports standard CRUD operations for webhooks:
- Create: Register a new endpoint URL and select the event types to subscribe to.
- Update: Modify an existing webhook's URL, status (enabled/disabled), or subscribed events.
- List/Get: Retrieve configurations for one or all registered webhooks.
- Remove: Delete a webhook configuration.
Sources: resend/webhooks/_webhooks.py:342-458, tests/webhooks_test.py:20-112
Event Inspection and Replay
You can track the history of events sent to a specific webhook. This includes listing all delivered events, retrieving specific event details, and replaying an event if your server failed to process it initially.
Sources: resend/webhooks/_webhooks.py:408-458, tests/webhooks_test.py:91-165
Webhook Signature Verification
Resend uses HMAC-SHA256 signatures to ensure that webhook requests originate from Resend and have not been tampered with. The SDK provides a verify() method that implements manual validation following the Svix standard.
Verification Logic
Verification requires the raw request body, the webhook signing secret, and the Svix headers provided in the incoming request.
The diagram shows the logical flow of the verify() method, starting from header extraction to the final signature comparison.
Sources: resend/webhooks/_webhooks.py:465-546, examples/webhook_receiver.py:46-75
Verification Requirements
The verify() method checks the following conditions:
- Header Presence: The request must include
svix-id,svix-timestamp, andsvix-signature. - Timestamp Tolerance: The difference between the current time and the
svix-timestampmust be within 300 seconds to prevent replay attacks. - Signature Match: The computed HMAC-SHA256 hash of the concatenated ID, timestamp, and body must match one of the signatures provided in the header.
Sources: resend/webhooks/_webhooks.py:494-546, tests/webhooks_test.py:237-332
Inbound Email Receiving
The Emails.Receiving module retrieves emails sent to your Resend inbound addresses. This API provides access to the full email content, including MIME headers and attachments.
Retrieving Inbound Emails
You can retrieve a single email by its unique identifier or list emails with pagination.
| Feature | Description |
|---|---|
| Email Content | Accesses html, text, and subject fields. |
| Recipients | Provides from, to, cc, bcc, and reply_to arrays. |
| MIME Headers | Accesses original email headers (e.g., DKIM-Signature). |
| Attachments | Lists attachment metadata including filename, size, and content type. |
Sources: examples/receiving_email.py:12-65, tests/emails_test.py:406-460
Attachment Management
Inbound emails include metadata for attachments. While metadata is part of the email object, the SDK provides methods to list all attachments for a specific email and retrieve detailed information, including temporary download URLs.
The sequence shows the two-step process of retrieving an email and then obtaining a specific attachment's download URL.
Sources: examples/receiving_email.py:120-160, resend/init.py:81-84
Webhook Event Data Structures
Webhook payloads vary based on the event type. All payloads share a common structure: a type, created_at timestamp, and a data object.
Outbound Email Events
Events such as email.sent, email.delivered, and email.bounced share a base data structure.
| Field | Type | Description |
|---|---|---|
email_id | string | Unique identifier for the email. |
to | string[] | Recipients impacted by the event. |
message_id | string | The RFC Message-ID header. |
bounce | object | (Only for email.bounced) Includes type, subType, and diagnosticCode. |
click | object | (Only for email.clicked) Includes link, ipAddress, and userAgent. |
Sources: resend/webhooks/_webhook_event.py:101-180, tests/webhooks_test.py:334-375
Inbound Email Events
The email.received event payload provides high-level metadata about the inbound message.
| Field | Type | Description |
|---|---|---|
from | string | The sender's email address. |
subject | string | The subject of the email. |
received_for | string[] | The original recipient address (useful for forwarding). |
attachments | object[] | Metadata for files included in the message. |
Sources: resend/webhooks/_webhook_event.py:183-216, tests/webhooks_test.py:311-332
Summary
The Receiving and Webhooks features enable bidirectional communication with the Resend platform. Webhooks provide an asynchronous notification mechanism for tracking the lifecycle of sent emails and reacting to system changes. The Receiving API complements this by offering programmatic access to inbound communication, allowing applications to process incoming messages and files securely. Together, these systems provide the necessary infrastructure for building complex email-driven workflows and integrations.