Create a webhook endpoint

Registers a URL to receive delivery events as they happen.

Delivery is at least once, so the same event can arrive twice — key your handling on the event id and make it idempotent. Events can also arrive out of order; a delivered before the accepted that preceded it is normal and not a bug.

Verify the signature on every request before trusting the body. See Receiving webhooks for the full list of events and their payloads.

What an email.inbound event carries. The sender, the recipients and the subject of an email that arrived, and for some messages its body. It goes to every webhook in your account that subscribes to it and whose filters it passes — so an unfiltered webhook gets the incoming mail of every mailbox on every domain in your account, not only the mailbox your integration uses. domain narrows it to one domain's mailboxes; there is no filter for a single mailbox, so check the recipient on your side if you need one.

Incoming mail needs a domain when your account has more than one. A webhook subscribed to email.inbound must then set domain (one of yours, exact match). Leaving it out answers 422 on domain — on create, on an update that would remove it, and when turning an old webhook back on. With one domain it is optional; when you add a second domain, a webhook without one is tied to the domain you had, so it keeps getting exactly what it got before.

Filters, three ways, one result. The domain can be sent as domain, filters.domain or targeting.domain; the top-level domain wins when it is sent. filters uses the stored names (senderIncludes, subjectContains, bodyContains); targeting uses the names the response returns (sender_includes, ...), so you can send back what you read. Send one of the two, not both. Every call answers with targeting: read it back to confirm what is applied. Anything unknown is a 422 that names it — a field, a filter key, or an event name — never a 200 that quietly ignored it.

email.deferred usually means we are still trying. The receiving server asked us to wait, the message is in our queue, and we retry it for you. One is not ours to retry: when a marketing SMTP key sends to a contact whose inbox is full and Bounce protection is holding marketing to them, the message is refused before it is queued (a 452 that names a date). It is logged deferred, but Mailyte never queued it, so your app must send it again after the date in the reason.

Three account events are about your account, not about a message, so a webhook's domain, sender, subject and body filters never hold them back. They are sent only once Bounce protection is on for your account.

• contact.checked: a contact's address was checked and the answer changed, once per change. {contact_id, email, email_status, reason, suggestion, checked_at, email_full_until}. email_status is the contact's new value; reason and suggestion read as on a verification result (suggestion is the corrected address for a misspelt domain, else null). unknown with a checker that could not confirm yet is asked again later and may be announced again. email_full_until is the end of a hold on marketing to a full inbox while it runs, else null.
• checks.running_low: {trigger, plan_left, bought, credit_fallback, forecast_days}. trigger is forecast (under 7 days of checks left at your recent pace) or plan_80 (80% of this month's plan checks used, and none bought). The counts are checks, as on GET /billing/usage.
• checks.ran_out: {since, buy_path}. A new contact could not be checked because no checks were left; it was added as not_checked. buy_path is the dashboard page that buys the checks we suggest.

The two checks.* events are sent at most once per cycle: a new month, a purchase or checks added by us start a new one.

curl -X POST 'https://app.mailyte.com/api/v1/webhooks' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Production events",
    "events": [
      "email.delivered",
      "email.bounced"
    ],
    "url": "https://example.com/webhooks/mailyte"
  }'

const response = await fetch('https://app.mailyte.com/api/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mk_live_YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Production events",
    "events": [
      "email.delivered",
      "email.bounced"
    ],
    "url": "https://example.com/webhooks/mailyte"
  }),
});
const { data } = await response.json();

import requests
response = requests.post(
    "https://app.mailyte.com/api/v1/webhooks",
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={
      "name": "Production events",
      "events": [
        "email.delivered",
        "email.bounced"
      ],
      "url": "https://example.com/webhooks/mailyte"
    },
)
data = response.json()["data"]

<?php

$response = Http::withToken('mk_live_YOUR_API_KEY')
    ->post('https://app.mailyte.com/api/v1/webhooks', [
    'name' => 'Production events',
    'events' => [
        'email.delivered',
        'email.bounced',
    ],
    'url' => 'https://example.com/webhooks/mailyte',
]);

$data = $response->json('data');

require "net/http"
require "json"
uri = URI("https://app.mailyte.com/api/v1/webhooks")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer mk_live_YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = {
  "name": "Production events",
  "events": [
    "email.delivered",
    "email.bounced"
  ],
  "url": "https://example.com/webhooks/mailyte"
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }