Webhook payload reference

This page is for developers building something to receive EcoSend's webhooks. It lists every field EcoSend sends, with an example of each event.

New to webhooks in EcoSend? Start with sending activity to other tools with webhooks to set one up.

Each request contains a JSON payload describing a single event.

Event types

The type field tells you which trigger fired.

Trigger	type
Email sent	email-sent
Email delivered	email-delivered
Email opened	email-opened
Email link clicked	link-clicked
Email bounced	email-bounced
Email marked as spam	email-complained

Smart Group triggers send a different payload. To see exactly what they contain, send one to a request inspector first, as described in things to know.

Common fields

Every email activity payload includes these fields.

Field	Description
version	The version of the payload format, currently 0.0.1. This is unlikely to change, but if we ever change the structure we’ll update this.
type	The event that happened. See event types.
timestamp	When the event happened, as a Unix timestamp in milliseconds.
person_id	The contact the event relates to.
email.id	A unique ID for the individual email. Every event for the same email shares this ID, so you can use it to group them.
email.from	The sender name and address the email was sent from.
email.to	The contact's email address.
email.subject	The subject line of the email.
source.type	What sent the email: broadcast, automated-message, or sequence.
source.id	The ID of the Broadcast, automated message, or sequence that sent the email. Useful for tracing an event back to what sent it.
source.message	Sequences only. The ID of the message within the sequence.

Some events include extra fields, which are described alongside their examples below.

Email sent

{
  "version": "0.0.1",
  "type": "email-sent",
  "timestamp": 1791032473006,
  "person_id": "email:someone@example.com",
  "email": {
    "id": "010001a101dab4d9-7d91daab-33b0-4195-8a05-d5a8a52cae5a-000000@email.amazonses.com",
    "from": "Example Sender <sender@example.com>",
    "to": "someone@example.com",
    "subject": "Example Subject Line"
  },
  "source": {
    "type": "broadcast",
    "id": "2b2cdcbc-7d6e-4c19-8c5a-d36095f0bbe5"
  }
}

Email delivered

{
  "version": "0.0.1",
  "type": "email-delivered",
  "timestamp": 1791032482986,
  "person_id": "email:someone@example.com",
  "source": {
    "type": "broadcast",
    "id": "6975c4e5-dac5-4693-b9cd-4e4ec2dd0783"
  },
  "email": {
    "id": "010001a101dadab7-1fbb1491-4938-429a-b7e3-da8fb76c8477-000000@email.amazonses.com",
    "from": "Example Sender <sender@example.com>",
    "to": "someone@example.com",
    "subject": "Example Subject Line"
  }
}

Email opened

{
  "version": "0.0.1",
  "type": "email-opened",
  "timestamp": 1791032484326,
  "person_id": "email:someone@example.com",
  "source": {
    "type": "broadcast",
    "id": "6975c4e5-dac5-4693-b9cd-4e4ec2dd0783"
  },
  "email": {
    "id": "010001a101dadab7-1fbb1491-4938-429a-b7e3-da8fb76c8477-000000@email.amazonses.com",
    "from": "Example Sender <sender@example.com>",
    "to": "someone@example.com",
    "subject": "Example Subject Line"
  }
}

Email link clicked

Includes url, the link the contact clicked.

{
  "version": "0.0.1",
  "type": "link-clicked",
  "timestamp": 1791032654624,
  "person_id": "email:someone@example.com",
  "url": "https://example.com",
  "source": {
    "type": "broadcast",
    "id": "2b2cdcbc-7d6e-4c19-8c5a-d36095f0bbe5"
  },
  "email": {
    "id": "010001a101dab4d9-7d91daab-33b0-4195-8a05-d5a8a52cae5a-000000@email.amazonses.com",
    "from": "Example Sender <sender@example.com>",
    "to": "someone@example.com",
    "subject": "Example Subject Line"
  }
}

Email bounced

Includes a bounce object:

• bounce.type: the kind of bounce, such as permanent. See understanding bounces for the difference between bounce types.
• bounce.reason: the response from the contact's mail server explaining why the email bounced.

{
  "version": "0.0.1",
  "type": "email-bounced",
  "timestamp": 1791032473548,
  "person_id": "email:someone@example.com",
  "bounce": {
    "type": "permanent",
    "reason": "550 5.1.1 As requested: user unknown <someone@example.com>"
  },
  "source": {
    "type": "broadcast",
    "id": "2b2cdcbc-7d6e-4c19-8c5a-d36095f0bbe5"
  },
  "email": {
    "id": "010001a101dab4d9-7d91daab-33b0-4195-8a05-d5a8a52cae5a-000000@email.amazonses.com",
    "from": "Example Sender <sender@example.com>",
    "to": "someone@example.com",
    "subject": "Example Subject Line"
  }
}

Email marked as spam

Includes a complaint object, where complaint.type describes the complaint, such as abuse.

{
  "version": "0.0.1",
  "type": "email-complained",
  "timestamp": 1791032483316,
  "person_id": "email:someone@example.com",
  "complaint": {
    "type": "abuse"
  },
  "source": {
    "type": "broadcast",
    "id": "6975c4e5-dac5-4693-b9cd-4e4ec2dd0783"
  },
  "email": {
    "id": "010001a101dadab7-1fbb1491-4938-429a-b7e3-da8fb76c8477-000000@email.amazonses.com",
    "from": "Example Sender <sender@example.com>",
    "to": "someone@example.com",
    "subject": "Example Subject Line"
  }
}

Need a hand?

If you have any questions about setting up webhooks, or want ideas for your own setup, get in touch and we'll be happy to help.