Sign in

v49

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

Domain DNS Error

Triggered when there's a DNS configuration issue with your sending domain.

This event indicates that your domain's DNS records (SPF, DKIM, MX, or Return Path) may be misconfigured or have become invalid. This can affect email deliverability.

Payload structure: This event has a different structure than message events:

  • server: Information about the server that owns this domain
  • domain: The domain name with DNS issues
  • uuid: Unique identifier for the domain
  • dns_checked_at: Timestamp when DNS was checked
  • Individual status and error fields for SPF, DKIM, MX, and Return Path

Action required: Check your domain's DNS settings in the dashboard and verify all records are correctly configured.

postWebhookDomainDNSError

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