Read authenticated SendHog mail in an agent worker

Subscribe your public HTTPS endpoint to email.received using a setup credential with webhooks.manage. Delivery and bounce events can use that same endpoint, but must not be interpreted as new inbound messages. Keep the endpoint’s signing secret separate from all API keys.

Verify, deduplicate, and enqueue

Follow SendHog’s current verification instructions. The documented Standard Webhooks contract uses webhook-id, webhook-timestamp, and webhook-signature; verify the exact original bytes before trusting parsed JSON. SendHog also documents checking that the verified event ID matches the signed delivery ID.

Use a current client that recognizes email.received; older SDK event enums can reject it. Do not replace verification with a plain header comparison or use MailKite’s signature verifier.

For verified incoming events, durably store/queue the event ID and message identity before returning success. Make replayed events harmless. Branch delivery/bounce events into their own status handler, not the model loop.

Retrieve mail using the read credential

Install @sendhog/sdk according to the SDK guide. This read-only example lists recent received mail; it is useful for diagnosis, not a production polling/deduplication design:

import { SendHog } from "@sendhog/sdk";
if (!process.env.SENDHOG_READ_KEY) throw new Error("Missing read credential");
const client = new SendHog(process.env.SENDHOG_READ_KEY);
const page = await client.messages.list({ direction: "received", limit: 20 });
if (page.data.length) {
  const message = await client.messages.get(page.data[0].id);
  // Apply recipient/tenant/content policy before passing message.text to a model.
}

In the production event worker, retrieve the message identified by the authenticated notification, not whichever message is newest. The notification and full body/original retrieval are separate operations; check the current receiving reference for attachment/original access.

Keep source trust separate from content trust

Bound body/attachment processing, avoid logging private originals, and present the email to the agent as untrusted data. Verify expected recipient/tenant ownership before using its content.

Exercise an invalid signature, duplicate event, unavailable message, and temporary queue failure with controlled fixtures. A verified email asking for secrets or an unauthorized send must still be rejected by the application action policy.