API ReferenceWebhooks

Webhooks Overview

Webhooks enable real-time notifications about your email activity. Instead of polling our API for delivery status, we push event data to your server as it happens.

Valid Event Types

Webhook Event Payloads

All webhook payloads delivered to your endpoints share a common outer envelope. Below are the specific payload details for each event type.

Outbound Email Events

email_sentOutbound

Sent as soon as our server successfully hands off the email to the sending provider.

{
  "id": "evt_1782201118808_9c6a1f8e",
  "type": "email_sent",
  "created": "2026-06-23T08:11:58.808Z",
  "livemode": true,
  "data": {
    "object": {
      "emailId": "email_1782200882775_abc123",
      "messageId": "msg_0100019a3908b26b",
      "from": "sender@yourdomain.com",
      "to": [
        "[email protected]"
      ],
      "timestamp": "2026-06-23T08:11:58.808Z"
    }
  }
}

email_deliveredOutbound

Sent when the destination mail server confirms the email was successfully accepted.

{
  "id": "evt_1782201122124_3f7b2c9a",
  "type": "email_delivered",
  "created": "2026-06-23T08:12:02.124Z",
  "livemode": true,
  "data": {
    "object": {
      "emailId": "email_1782200882775_abc123",
      "messageId": "msg_0100019a3908b26b",
      "from": "sender@yourdomain.com",
      "recipient": "[email protected]",
      "timestamp": "2026-06-23T08:12:02.124Z"
    }
  }
}

email_openedOutbound

Sent when the recipient opens the email (requires open tracking enabled on the send request).

{
  "id": "evt_1782201225000_7d1e8f2c",
  "type": "email_opened",
  "created": "2026-06-23T08:13:45.000Z",
  "livemode": true,
  "data": {
    "object": {
      "emailId": "email_1782200882775_abc123",
      "messageId": "msg_0100019a3908b26b",
      "from": "sender@yourdomain.com",
      "recipient": "[email protected]",
      "timestamp": "2026-06-23T08:13:45.000Z",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
      "ipAddress": "192.0.2.1"
    }
  }
}

email_clickedOutbound

Sent when the recipient clicks any tracked link within the email (requires click tracking enabled on the send request).

{
  "id": "evt_1782201252000_1a4d9e5b",
  "type": "email_clicked",
  "created": "2026-06-23T08:14:12.000Z",
  "livemode": true,
  "data": {
    "object": {
      "emailId": "email_1782200882775_abc123",
      "messageId": "msg_0100019a3908b26b",
      "from": "sender@yourdomain.com",
      "recipient": "[email protected]",
      "timestamp": "2026-06-23T08:14:12.000Z",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
      "ipAddress": "192.0.2.1",
      "link": "https://example.com/click-here"
    }
  }
}

email_bouncedOutbound

Sent when a hard or soft bounce occurs. Contains type, subtype, and SMTP diagnostic code response from the recipient server.

{
  "id": "evt_1782201130000_2f8c6e7d",
  "type": "email_bounced",
  "created": "2026-06-23T08:12:10.000Z",
  "livemode": true,
  "data": {
    "object": {
      "emailId": "email_1782200882775_abc123",
      "messageId": "msg_0100019a3908b26b",
      "from": "sender@yourdomain.com",
      "recipient": "[email protected]",
      "timestamp": "2026-06-23T08:12:10.000Z",
      "bounceType": "Permanent",
      "bounceSubType": "General",
      "diagnosticCode": "smtp; 550 5.1.1 The email account that you tried to reach does not exist."
    }
  }
}

email_complainedOutbound

Sent when a recipient marks the email as spam or abuse through their mailbox provider.

{
  "id": "evt_1782201322000_5a9b8c7d",
  "type": "email_complained",
  "created": "2026-06-23T08:15:22.000Z",
  "livemode": true,
  "data": {
    "object": {
      "emailId": "email_1782200882775_abc123",
      "messageId": "msg_0100019a3908b26b",
      "from": "sender@yourdomain.com",
      "recipient": "[email protected]",
      "timestamp": "2026-06-23T08:15:22.000Z",
      "feedbackType": "abuse"
    }
  }
}

email_unsubscribedOutbound

Sent when the recipient unsubscribes using the headers or footer link.

{
  "id": "evt_1782201365000_3e7f9a2b",
  "type": "email_unsubscribed",
  "created": "2026-06-23T08:16:05.000Z",
  "livemode": true,
  "data": {
    "object": {
      "emailId": "email_1782200882775_abc123",
      "messageId": "msg_0100019a3908b26b",
      "from": "sender@yourdomain.com",
      "recipient": "[email protected]",
      "timestamp": "2026-06-23T08:16:05.000Z"
    }
  }
}

email_delayedOutbound

Sent when delivery is temporarily delayed by the recipient server (e.g., due to rate limiting or transient mail server issues).

{
  "id": "evt_1782201150000_9e5f8d2c",
  "type": "email_delayed",
  "created": "2026-06-23T08:12:30.000Z",
  "livemode": true,
  "data": {
    "object": {
      "emailId": "email_1782200882775_abc123",
      "messageId": "msg_0100019a3908b26b",
      "from": "sender@yourdomain.com",
      "recipients": [
        "[email protected]"
      ],
      "timestamp": "2026-06-23T08:12:30.000Z",
      "delayType": "TransientFailure",
      "expirationTime": "2026-06-25T08:12:30.000Z"
    }
  }
}

email_suppressedOutbound

Sent when SimplySend drops the message because the recipient is already on your suppression list (e.g., due to a prior bounce or complaint).

{
  "id": "evt_1782201119000_9e5f8d3d",
  "type": "email_suppressed",
  "created": "2026-06-23T08:12:00.000Z",
  "livemode": true,
  "data": {
    "object": {
      "emailId": "email_1782200882775_abc123",
      "messageId": "msg_0100019a3908b26b",
      "from": "sender@yourdomain.com",
      "recipient": "[email protected]",
      "timestamp": "2026-06-23T08:12:00.000Z"
    }
  }
}

Note: email_failed and email_rejected share the same simple object payload structure as email_suppressed.

Inbound Email Events

email_receivedInbound

Sent when an inbound email is successfully received by your SimplySend inbox. Contains message content, headers, domain identification, and attachments status.

{
  "id": "evt_1782200635343_a1b2c3d4",
  "type": "email_received",
  "created": "2026-06-23T07:43:55.343Z",
  "livemode": true,
  "data": {
    "object": {
      "messageId": "<[email protected]>",
      "domainId": "yourdomain.com",
      "domain": "yourdomain.com",
      "from": "\"Jane Doe\" <[email protected]>",
      "to": "hello@yourdomain.com",
      "subject": "Some test",
      "snippet": "Hi there, this is a test inbound email.",
      "hasAttachments": false,
      "timestamp": "2026-06-23T07:43:55.343Z"
    }
  }
}

Domain Resource Events

domain_createdResource

Sent when a new domain is registered in your account.

{
  "id": "evt_1782200635343_d5e6f7a8",
  "type": "domain_created",
  "created": "2026-06-23T07:43:55.343Z",
  "livemode": true,
  "data": {
    "object": {
      "domainId": "dom_1782200635343_abc",
      "domain": "yourdomain.com",
      "timestamp": "2026-06-23T07:43:55.343Z"
    }
  }
}

domain_verifiedResource

Sent when DNS verification check succeeds and domain status becomes verified.

{
  "id": "evt_1782200645000_f9e8d7c6",
  "type": "domain_verified",
  "created": "2026-06-23T07:44:05.000Z",
  "livemode": true,
  "data": {
    "object": {
      "domainId": "dom_1782200635343_abc",
      "domain": "yourdomain.com",
      "timestamp": "2026-06-23T07:44:05.000Z"
    }
  }
}

Note: domain_deleted and domain_unverified share the same payload structure as domain_created, with the type field set to the corresponding event type name.

Domain Group Events

domain_group_createdResource

Sent when a new domain segregation group is created.

{
  "id": "evt_1782200635343_g4h5j6k7",
  "type": "domain_group_created",
  "created": "2026-06-23T07:43:55.343Z",
  "livemode": true,
  "data": {
    "object": {
      "groupId": "group_1782200635343_xyz",
      "name": "Transactional Emails",
      "timestamp": "2026-06-23T07:43:55.343Z"
    }
  }
}

Note: domain_group_updated and domain_group_deleted share the same payload structure as domain_group_created, with the type field set to the corresponding event type name.