API Reference

Webhooks

Receive real-time HTTP notifications when events occur in your inboxes. No more polling — get instant delivery of new messages to your server.

Webhook Object

Field	Type	Description
id	uuid	Unique webhook identifier
user_id	uuid	Owner user ID
url	string	Destination URL for webhook delivery
events	string[]	Event types to subscribe to
secret	string	HMAC secret for verifying webhook signatures
active	bool	Whether the webhook is currently active
created_at	timestamp	When the webhook was created

Event Types

Subscribe to specific events or leave empty to receive all events.

message.received

A new inbound email was received in any of your inboxes

message.sent

An outbound email was successfully sent

inbox.created

A new inbox was created

inbox.expired

A temporary inbox has expired

Webhook Payload

When an event fires, AgentEmail sends a POST request to your URL with this payload:

{
  "event": "message.received",
  "timestamp": "2026-03-27T15:30:00Z",
  "data": {
    "inbox_id": "inbox-uuid...",
    "message_id": "msg-uuid...",
    "from": "sender@example.com",
    "subject": "Your verification code"
  }
}

Verify authenticity by checking the X-Webhook-Signature header against the HMAC-SHA256 of the payload using your webhook secret.

POST/api/v1/webhooksAPI Key

Create Webhook

Subscribe to events with a webhook URL. A secret is auto-generated for signature verification.

Request Body

urlstring*

HTTPS URL to receive webhook events

eventsstring[]

Event types to subscribe to (empty = all events)

cURL

curl -X POST https://api.agentemail.email/api/v1/webhooks \
  -H "X-API-Key: ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.com/webhook","events":["message.received"]}'

Response

{
  "success": true,
  "data": {
    "id": "wh-uuid...",
    "url": "https://your-server.com/webhook",
    "events": ["message.received"],
    "secret": "whsec_...",
    "active": true
  }
}

GET/api/v1/webhooksAPI Key

List Webhooks

List all webhook subscriptions for the authenticated user.

cURL

curl https://api.agentemail.email/api/v1/webhooks \
  -H "X-API-Key: ak_your_key"

DELETE/api/v1/webhooks/{id}API Key

Delete Webhook

Remove a webhook subscription. Events will no longer be delivered to this URL.

Path Parameters

iduuid

Webhook ID

cURL

curl -X DELETE https://api.agentemail.email/api/v1/webhooks/{id} \
  -H "X-API-Key: ak_your_key"