Skip to main content

​
Event Types Overview

Webhook events are namespaced by service (outbound or inbound). Subscribe to the events relevant to your use case.

​
Outbound Events

EventDescription
outbound.queuedMessage entered the queue
outbound.deliveredMessage successfully delivered
outbound.deferredMessage temporarily deferred
outbound.bouncedMessage bounced (hard or soft)
outbound.rejectedMessage rejected by remote server
outbound.spamMessage flagged as spam
outbound.virusVirus detected in message
outbound.droppedMessage dropped (policy/rate limit)
outbound.openedRecipient opened the email
outbound.clickedRecipient clicked a link
outbound.complaintSpam complaint received (FBL)

​
Inbound Events

EventDescription
inbound.receivedMessage received at our servers
inbound.deliveredMessage delivered to your mailbox
inbound.spamMessage marked as spam
inbound.blockedMessage blocked by policy

​
Outbound Event Payloads

​
outbound.queued

Triggered when a message enters the queue. 
{
    "id": "evt_abc123",
    "service": "outbound",
    "type": "outbound.queued",
    "created_at": 1704825600,
    "data": {
        "uid": "message-uid",
        "from": "[email protected]",
        "to": "[email protected]",
        "subject": "Hello World",
        "user": "api-user"
    }
}

​
outbound.delivered

Triggered when a message is successfully delivered. 
{
    "id": "evt_abc123",
    "service": "outbound",
    "type": "outbound.delivered",
    "created_at": 1704825600,
    "data": {
        "uid": "message-uid",
        "from": "[email protected]",
        "to": "[email protected]",
        "subject": "Hello World",
        "mx": "aspmx.l.google.com",
        "host": "2404:6800:4003:c1a::1b",
        "ip": "2001:df4:2980:15::1",
        "response": "250 2.0.0 OK"
    }
}

​
outbound.bounced

Triggered when a message bounces. 
{
    "id": "evt_abc123",
    "service": "outbound",
    "type": "outbound.bounced",
    "created_at": 1704825600,
    "data": {
        "uid": "message-uid",
        "from": "[email protected]",
        "to": "[email protected]",
        "bounce_type": "hard",
        "mx": "mx.example.com",
        "host": "192.0.2.1",
        "response": "550 User unknown"
    }
}
The bounce_type field indicates whether it was a hard bounce (permanent) or soft bounce (temporary).

​
outbound.rejected

Triggered when a message is rejected by the remote mail server. 
{
    "id": "evt_abc123",
    "service": "outbound",
    "type": "outbound.rejected",
    "created_at": 1704825600,
    "data": {
        "uid": "message-uid",
        "from": "[email protected]",
        "to": "[email protected]",
        "mx": "mx.example.com",
        "host": "192.0.2.1",
        "response": "550 5.7.1 Message rejected due to policy"
    }
}

​
outbound.deferred

Triggered when a message is temporarily deferred by the remote mail server. 
{
    "id": "evt_abc123",
    "service": "outbound",
    "type": "outbound.deferred",
    "created_at": 1704825600,
    "data": {
        "uid": "message-uid",
        "from": "[email protected]",
        "to": "[email protected]",
        "mx": "mx.example.com",
        "host": "192.0.2.1",
        "response": "451 4.7.1 Try again later"
    }
}

​
outbound.spam

Triggered when a message is flagged as spam before delivery. 
{
    "id": "evt_abc123",
    "service": "outbound",
    "type": "outbound.spam",
    "created_at": 1704825600,
    "data": {
        "uid": "message-uid",
        "from": "[email protected]",
        "to": "[email protected]",
        "subject": "Buy now!!!",
        "score": 15.3,
        "rules": "URIBL_BLOCKED,HTML_IMAGE_RATIO_02"
    }
}

​
outbound.virus

Triggered when a virus is detected in a message. 
{
    "id": "evt_abc123",
    "service": "outbound",
    "type": "outbound.virus",
    "created_at": 1704825600,
    "data": {
        "uid": "message-uid",
        "from": "[email protected]",
        "to": "[email protected]",
        "subject": "Document attached",
        "response": "Virus detected: Eicar-Test-Signature"
    }
}

​
outbound.dropped

Triggered when a message is dropped due to policy or rate limiting. 
{
    "id": "evt_abc123",
    "service": "outbound",
    "type": "outbound.dropped",
    "created_at": 1704825600,
    "data": {
        "uid": "message-uid",
        "from": "[email protected]",
        "to": "[email protected]",
        "response": "Rate limit exceeded"
    }
}

​
outbound.opened

Triggered when a recipient opens an email (requires open tracking enabled). 
{
    "id": "evt_abc123",
    "service": "outbound",
    "type": "outbound.opened",
    "created_at": 1704825600,
    "data": {
        "uid": "message-uid",
        "country": "AU",
        "email_client": "Gmail",
        "user_agent": "Mozilla/5.0..."
    }
}

​
outbound.clicked

Triggered when a recipient clicks a link (requires click tracking enabled). 
{
    "id": "evt_abc123",
    "service": "outbound",
    "type": "outbound.clicked",
    "created_at": 1704825600,
    "data": {
        "uid": "message-uid",
        "url": "https://example.com/promo",
        "country": "AU",
        "user_agent": "Mozilla/5.0..."
    }
}

​
outbound.complaint

Triggered when a spam complaint is received via feedback loop (FBL). 
{
    "id": "evt_abc123",
    "service": "outbound",
    "type": "outbound.complaint",
    "created_at": 1704825600,
    "data": {
        "uid": "message-uid",
        "from": "[email protected]",
        "to": "[email protected]"
    }
}
Spam complaints can negatively impact your sender reputation. Monitor these closely and remove recipients who complain from your mailing lists.

​
Inbound Event Payloads

​
inbound.received

Triggered when a message is first received at our servers. 
{
    "id": "evt_def456",
    "service": "inbound",
    "type": "inbound.received",
    "created_at": 1704825600,
    "data": {
        "uid": "message-uid",
        "from": "[email protected]",
        "to": "[email protected]",
        "subject": "Hello",
        "domain": "yourdomain.com",
        "host": "mail.sender.com",
        "ip": "203.0.113.1"
    }
}

​
inbound.delivered

Triggered when a message is successfully delivered to your mailbox. 
{
    "id": "evt_def456",
    "service": "inbound",
    "type": "inbound.delivered",
    "created_at": 1704825600,
    "data": {
        "uid": "message-uid",
        "from": "[email protected]",
        "to": "[email protected]",
        "subject": "Hello",
        "domain": "yourdomain.com",
        "response": "250 OK"
    }
}

​
inbound.spam

Triggered when a message is marked as spam. 
{
    "id": "evt_def456",
    "service": "inbound",
    "type": "inbound.spam",
    "created_at": 1704825600,
    "data": {
        "uid": "message-uid",
        "from": "[email protected]",
        "to": "[email protected]",
        "subject": "You won!!!",
        "domain": "yourdomain.com",
        "spam_score": 12.5,
        "spam_report": "URIBL_BLOCKED,BAYES_99"
    }
}

​
inbound.blocked

Triggered when a message is blocked by policy. 
{
    "id": "evt_def456",
    "service": "inbound",
    "type": "inbound.blocked",
    "created_at": 1704825600,
    "data": {
        "uid": "message-uid",
        "from": "[email protected]",
        "to": "[email protected]",
        "domain": "yourdomain.com",
        "response": "550 5.7.1 Sender blocked by policy"
    }
}

​
Common Payload Fields

All webhook payloads share these common fields:
FieldTypeDescription
idstringUnique event identifier (format: evt_xxx)
servicestringEither outbound or inbound
typestringThe event type
created_atintegerUnix timestamp when the event occurred
dataobjectEvent-specific data

​
Data Object Fields

FieldEventsDescription
uidAllUnique message identifier
fromMostSender email address
toMostRecipient email address
subjectSomeEmail subject line
domainInboundRecipient domain
responseDelivery eventsServer response message
mxOutbound deliveryMail exchanger used
hostDelivery eventsServer hostname or IP
ipSomeIP address