Deliver email to a webhook

When you finish, every email to orders@lunavera.com reaches your server as a JSON POST that you can check and act on.

1. Put your URL in the destination#

   Open your domain’s Forwarding tab, then create an alias with Create alias or open an existing one with Edit alias.

   In Destinations, enter the URL and press Enter. Add any email addresses that should also get the message the same way. Mailyoto treats an entry that starts with https:// or http:// as a webhook, and anything else as an email address.

   Address

   orders

   Destinations

   https://shop.lunavera.com/hooks/orders, amina.kone@gmail.com

   

   A rule can forward to the URL too: choose Forward under Then and enter the URL as a destination.

2. Copy the signing secret#

   Open the domain’s Settings tab and find Webhook signing. Select Reveal and copy the Signing secret into your server’s configuration.

   

   Each domain has its own secret. Keep it on the server only.

3. Send a test#

   On the Forwarding tab, use Send test (the paper plane) on the alias.

   Open Logs. A delivery your endpoint accepted reads 250 Endpoint accepted it with HTTP 200., with the status your endpoint sent.

What your endpoint receives#

Each request is a POST with a JSON body that holds one email. It carries these headers:

The body starts with what Mailyoto knows about the delivery:

message always has every field below. Your code never has to check whether a field exists.

A shortened example:

{
  "id": "log_01m5pf2v9y4b8d1x6s3w0c7nqa",
  "attempt": 1,
  "received_at": "2026-10-23T09:14:05Z",
  "envelope": {
    "mail_from": "diego@harborpine.net",
    "rcpt_to": "orders@lunavera.com",
    "helo": "mail.harborpine.net",
    "client_ip": "203.0.113.7",
    "client_ptr": "mail.harborpine.net"
  },
  "authentication": [
    { "method": "dkim", "result": "pass", "domain": "harborpine.net" },
    { "method": "spf", "result": "pass", "domain": "harborpine.net" },
    { "method": "dmarc", "result": "pass", "domain": "harborpine.net" },
    { "method": "arc", "result": "none", "domain": null }
  ],
  "message": {
    "message_id": "CAF7k2xq81@mail.harborpine.net",
    "subject": "Order 1042",
    "sent_at": "2026-10-23T09:14:02Z",
    "from": { "name": "Diego Ramos", "address": "diego@harborpine.net" },
    "sender": null,
    "reply_to": [],
    "to": [{ "name": null, "address": "orders@lunavera.com" }],
    "cc": [],
    "bcc": [],
    "text": "Two boxes of the blue tiles, please.",
    "html": "<p>Two boxes of the blue tiles, please.</p>",
    "attachments": [
      { "filename": "order-1042.pdf", "content_type": "application/pdf", "size": 48213, "content": "JVBERi0xLjcK..." }
    ],
    "inline_images": [],
    "headers": { "subject": ["Order 1042"], "received": ["from mail.harborpine.net ..."] }
  },
  "raw_message": null,
  "raw_message_url": null
}

Check that a request came from Mailyoto#

Anyone who learns your URL can post to it. Mailyoto signs every request. Your endpoint can then refuse anything Mailyoto didn’t send. Each request carries 2 headers:

To check a request:

1. Keep the body as the exact bytes you received. Parsing the JSON and writing it out again changes the bytes.
2. Refuse the request if the timestamp is far from your server’s clock. The examples below allow 5 minutes, which stops someone replaying an old request.
3. Compute the HMAC-SHA256 of the timestamp, a dot and the raw body, with your secret as the key.
4. Compare your result with each sha256= value in Mailyoto-Signature, in constant time. Accept the request if one matches.

import hashlib
import hmac
import time

MAX_AGE_SECONDS = 5 * 60


def is_from_mailyoto(secret, timestamp, signature_header, raw_body):
    """raw_body is the request body as bytes, exactly as received."""
    if abs(time.time() - int(timestamp)) > MAX_AGE_SECONDS:
        return False
    expected = hmac.new(
        secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    return any(
        hmac.compare_digest(expected, entry.strip().removeprefix("sha256="))
        for entry in signature_header.split(",")
    )

const crypto = require("node:crypto");

const MAX_AGE_SECONDS = 5 * 60;

// rawBody is the request body as a Buffer, exactly as received.
function isFromMailyoto(secret, timestamp, signatureHeader, rawBody) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > MAX_AGE_SECONDS) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest();
  return signatureHeader.split(",").some((entry) => {
    const given = Buffer.from(entry.trim().replace(/^sha256=/, ""), "hex");
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

Change the secret#

Select Rotate secret under Webhook signing. For the next 24 hours, each request carries 2 signatures, one from the new secret and one from the old. Your endpoint keeps accepting requests while you deploy the new secret. The API can do the same: see the webhook signing secret on the API reference.

Change what the request carries#

Add these options to the URL as query parameters. They apply to that one destination.

https://shop.lunavera.com/hooks/orders?include_attachments=false&include_raw=true

Mailyoto refuses spam while the sending server is still connected. A refused email never reaches your endpoint. Use skip_spam_check=true when your own system filters spam.

Responses, timeouts and retries#

The gaps between tries are 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour and 3 hours, then 6 hours each. Each gap is up to 20% shorter or longer, so emails that failed together don’t all return at once. Mailyoto stops trying 3 days after the email arrived, with a last try at that moment.

Every try is in your email logs. A try that will be repeated has code 451, and its entry shows which try it was and when the next one runs. A delivery that stopped has code 554.

When your endpoint stops working#

Mailyoto pauses every alias and routing rule that delivers to your URL when:

• the endpoint responds 410, or
• an email still fails a day after it arrived, and no delivery to the URL succeeded that day.

You get one email that names the paused aliases and rules, and the last response. While an alias is paused, it holds new email for retry, unless you chose Return to sender or Discard quietly for it. A paused rule holds the email it matches for retry. Emails that arrived before the pause keep their tries.

To resume the webhook:

1. Make the endpoint respond with a 2xx status.
2. Select Resume on each paused alias and rule in Forwarding.
3. On the domain’s Usage and logs tab, resend any email that failed.