Webhook overview

Webhooks allow your application to receive information about email events as they occur. You can configure webhooks using the Webhooks settings page in your account.

Event types

There are multiple types of events when webhooks can be triggered. You can configure to send one or more of the following types of events:

  • Message Is Sent - message has been sent successfully
  • Message Is Opened - recipient opened a message. Will only occur when open tracking is enabled.

    That means LeaderSend adds a small, 1px by 1px graphic at the bottom of your HTML emails. When a recipient downloads images in your email, LeaderSend will record this as an open.
    LeaderSend can also record an open when a recipient clicks on a LeaderSend-tracked link. Since it's impossible to embed the tracking image in text-only emails, recipient clicks are the only way to track opens for text emails.

  • Message Is Clicked - recipient clicked a link in a message. Will only occur when click tracking is enabled
  • Message Recipient Unsubscribes - recipient unsubscribed. LeaderSend also automatically adds a List-Unsubscribe header to all emails. If recipients use an email program that supports this, like Hotmail, AOL or Yahoo, they can use the option in their email program to unsubscribe. Otherwise user has to send email by himself to email address provided in List-Unsubscribe header and enter keyword unsub in the subject line
  • Message Is Marked As Spam - spam filter detected or abuse reported message
  • Message Is Soft-Bounced - message has soft bounced
  • Message Is Bounced - message has hard bounced
  • Message Is Rejected - message was rejected. Recipient email address is rejected and added to the Rejection Blacklist when one of the following events occurs:
    • The recipient address bounces,
    • The recipient address registers an unsubscribe for an email sent to that address through the LeaderSend account.

    While an email address is active on the Rejection Blacklist, emails to the address will be given a state of rejected and LeaderSend will not attempt to deliver the emails. This helps to prevent sending emails to an email address that is no longer valid, may be having temporary issues, or doesn't wish to receive emails from you.
    Subsequent bounces or unsubscribe attempts results in an address being added to the rejection list.

Webhook or inbound route URL verification

When you provide the URL where you want LeaderSend to POST the data for events, we'll do a check that the URL exists by using a HEAD request. If the URL doesn't exist or returns something other than a 200 HTTP response to the HEAD request, LeaderSend will fallback.

Webhook format

Webhooks will send information about email events that contain JSON data to your URL address.

The webhook request is a standard POST request with a single parameter - leadersend_events. This parameter will contain a JSON-encoded array of the messages that match the webhook information. Each element in this array is a JSON object with following keys:

  • event - the name of the event type:
    • sent
    • open
    • click
    • unsubscribe
    • spam
    • soft_bounce
    • hard_bounce
    • reject
  • timestamp - unix timestamp when the event occurred
  • url - link that was clicked. Used for click event only
  • ip - client IP address where the event originated. Used for open and click events only
  • user_agent - the user agent string for the environment (ie, browser or email client) where the open or click occurred. Used for open and click events only
  • bounce_date - unix timestamp when the message bounced. Used for hard_bounce, soft_bounce and spam events only
  • open_date - unix timestamp when the message was opened. Used for open event only
  • click_date - unix timestamp when the link in the message was clicked. Used for click event only
  • unsubscribe_date - unix timestamp when recipient unsubscribes. Used for unsubscribe event only
  • msg - details about the message for which the event occurred
    • id - unique identifier assigned to each email sent via LeaderSend
    • timestamp - unix timestamp when the message was sent
    • email - recipient's email address
    • sender - sender's email address
    • subject - subject line of the message
    • opens - number of times the email is opened
    • clicks - number of tracked click times
    • delivery_report - bounced email report. Used only for bounced and soft-bounced messages
    • tags - array of tag attached to the message