Sign in

v49

latestOpenAPI 3.1.0Proprietaryraw.githubusercontent.com2026-02-185890337.1 KB
Email Events

Email Delivery Failed

Triggered when an email permanently fails to deliver (hard fail).

Common causes include:

  • Invalid recipient address (invalid_recipient)
  • Account disabled or suspended (inactive_mailbox)
  • Domain doesn't exist (invalid_domain)
  • Blocked by spam filters (spam_block, spam_content)
  • Policy rejection like DMARC failures (policy_rejection)

Unlike bounces, delivery failures may not generate a bounce notification to the sender.

Bounce Classification: This event includes classification data to help you understand why delivery failed permanently. Use the classification field for the category and smtp_enhanced_code for the standardized SMTP status code.

Suppression Lists: For invalid_recipient, inactive_mailbox, and invalid_domain classifications, you should add the address to your suppression list to avoid continued delivery attempts.

postWebhookMessageDeliveryFailed

Payload

status'Sent' | 'SoftFail' | 'HardFail' | 'Held'

Delivery status. Values correspond to event types:

  • Sent (MessageSent)
  • SoftFail (MessageDelayed)
  • HardFail (MessageDeliveryFailed)
  • Held (MessageHeld)
detailsstring

Human-readable summary of the delivery attempt. Format varies by status:

  • Sent: Message for {recipient} accepted by {ip}:{port} ({hostname})
  • SoftFail/HardFail: {code} {classification}: Delivery to {recipient} failed at {ip}:{port} ({hostname})
  • Connection errors: Connection error: Could not connect to any mail server for {domain}
outputstring

Raw SMTP response from the receiving server. Contains the full error message for failures.

sent_with_sslboolean

Whether the message was delivered over a TLS connection

timenumber float

Time taken to deliver in seconds

timestampnumber float

Unix timestamp of the delivery attempt (with microsecond precision)

classification'invalid_recipient' | 'inactive_mailbox' | 'mailbox_full' | 'invalid_domain' | 'dns_failure' | 'routing_error' | 'spam_block' | 'spam_content' | 'policy_rejection' | 'connection_error' | 'protocol_error' | 'transient_failure' | 'unclassified'

Bounce classification category explaining why delivery failed. Only present for MessageDelayed and MessageDeliveryFailed events.

Recipient Issues (10-19):

  • invalid_recipient - Mailbox doesn't exist (5.1.1)
  • inactive_mailbox - Account disabled or suspended
  • mailbox_full - Over quota (5.2.2)

Domain Issues (20-29):

  • invalid_domain - Domain doesn't exist
  • dns_failure - Temporary DNS resolution failure
  • routing_error - Relay denied or routing problems

Reputation/Policy (30-39):

  • spam_block - IP or domain blocklisted
  • spam_content - Content flagged as spam
  • policy_rejection - Rejected by policy (DMARC, etc.)

Technical (40-49):

  • connection_error - Connection timeout or refused
  • protocol_error - SMTP protocol issues
  • transient_failure - General temporary failure

Other:

  • unclassified - Could not classify the bounce
classification_code10 | 11 | 12 | 20 | 21 | 22 | 30 | 31 | 32 | 40 | 41 | 42 | 99

Numeric code for the bounce classification. Useful for grouping related classifications:

  • 10-19: Recipient issues
  • 20-29: Domain issues
  • 30-39: Reputation/policy issues
  • 40-49: Technical issues
  • 99: Unclassified

Only present when classification is present.

smtp_enhanced_codestring nullable

RFC 3463 enhanced SMTP status code from the receiving server (e.g., "5.1.1", "4.2.2"). Provides standardized bounce reason codes. Only present for delivery failures where the remote server provided an enhanced code.

remote_hoststring nullable

Hostname of the remote SMTP server that returned the error. Only present for delivery failures.

urlstring

The URL that was clicked (for MessageLinkClicked events)

tokenstring

Unique token for the clicked link (for MessageLinkClicked events)

ip_addressstring

IP address of the recipient (for MessageLoaded and MessageLinkClicked events)

user_agentstring

User agent of the recipient's email client (for MessageLoaded and MessageLinkClicked events)

domainstring

Domain name with DNS issues (for DomainDNSError events)

uuidstring

Unique identifier for the domain (for DomainDNSError events)

dns_checked_atnumber float

Unix timestamp when DNS was checked (for DomainDNSError events)

spf_status'OK' | 'Missing' | 'Invalid'

SPF record status (for DomainDNSError events)

spf_errorstring nullable

SPF error message if status is not OK

dkim_status'OK' | 'Missing' | 'Invalid'

DKIM record status (for DomainDNSError events)

dkim_errorstring nullable

DKIM error message if status is not OK

mx_status'OK' | 'Missing' | 'Invalid'

MX record status (for DomainDNSError events)

mx_errorstring nullable

MX error message if status is not OK

return_path_status'OK' | 'Missing' | 'Invalid'

Return path record status (for DomainDNSError events)

return_path_errorstring nullable

Return path error message if status is not OK

volumeinteger

Current send volume in the last hour (for SendLimit events)

limitinteger

Configured send limit per hour (for SendLimit events)

Example payload

{
  "message": {
    "id": 12345,
    "token": "abc123XYZ789",
    "direction": "outgoing",
    "message_id": "a1b2c3d4-e5f6-7890@rp.arkhq.io",
    "to": "user@example.com",
    "from": "hello@yourdomain.com",
    "subject": "Welcome to our service",
    "timestamp": 1704672000.123456,
    "spam_status": "NotChecked",
    "tag": "onboarding",
    "metadata": {
      "user_id": "usr_123456",
      "campaign_id": "camp_789012"
    }
  },
  "original_message": {
    "id": 12345,
    "token": "abc123XYZ789",
    "direction": "outgoing",
    "message_id": "a1b2c3d4-e5f6-7890@rp.arkhq.io",
    "to": "user@example.com",
    "from": "hello@yourdomain.com",
    "subject": "Welcome to our service",
    "timestamp": 1704672000.123456,
    "spam_status": "NotChecked",
    "tag": "onboarding",
    "metadata": {
      "user_id": "usr_123456",
      "campaign_id": "camp_789012"
    }
  },
  "bounce": {
    "id": 12345,
    "token": "abc123XYZ789",
    "direction": "outgoing",
    "message_id": "a1b2c3d4-e5f6-7890@rp.arkhq.io",
    "to": "user@example.com",
    "from": "hello@yourdomain.com",
    "subject": "Welcome to our service",
    "timestamp": 1704672000.123456,
    "spam_status": "NotChecked",
    "tag": "onboarding",
    "metadata": {
      "user_id": "usr_123456",
      "campaign_id": "camp_789012"
    }
  },
  "status": "Sent",
  "details": "Message for user@example.com accepted by 1.2.3.4:25 (mx.example.com)",
  "output": "250 2.0.0 OK",
  "sent_with_ssl": true,
  "time": 1.51,
  "timestamp": 1704672000.123456,
  "classification": "invalid_recipient",
  "classification_code": 10,
  "smtp_enhanced_code": "5.1.1",
  "remote_host": "mx1.gmail.com",
  "url": "https://yourdomain.com/welcome",
  "token": "abc123def456",
  "ip_address": "203.0.113.45",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
  "server": {
    "uuid": "a1b2c3d4-e5f6-7890",
    "name": "Production",
    "permalink": "production",
    "organization": "acme-corp"
  },
  "domain": "yourdomain.com",
  "uuid": "a1b2c3d4-e5f6-7890",
  "dns_checked_at": 1704672000.123456,
  "spf_status": "Missing",
  "spf_error": "No SPF record exists for this domain",
  "dkim_status": "OK",
  "mx_status": "OK",
  "return_path_status": "Missing",
  "return_path_error": "There is no return path record at rp.yourdomain.com",
  "volume": 950,
  "limit": 1000
}

Response

Webhook received successfully