Skip to main content
Version 2 delivers the parsed message in the webhook. Your endpoint gets subject, text, HTML, headers and links to the attachments without downloading and parsing the original message. The original stays available as a download. To use it, choose Version 2: parsed content under Payload when you add or edit the endpoint in the dashboard. The change applies to messages received afterwards; deliveries already created keep their version.

​
Format

The payload is the parsed content of the message for the recipient of the delivery, with two additional fields:
All fields are described under Parsed content. Note the differences to version 1:
  • The message fields are at the top level, not below message.
  • The envelope sender is called sender (version 1: envelope_from), the Message-ID header message-id (version 1: message_id).
  • Size and checksum of the original are in download.size_bytes and download.sha256.
Signature, headers, retries and deduplication are the same as for version 1. Talario does not imitate Mailgun’s signature fields; verify the X-Talario-Signature header.

​
Large messages

If the payload would exceed 1,000,000 bytes, Talario delivers it with content_omitted: true:
  • body-plain and body-html are "", and message-headers is [].
  • All other fields, the attachments with their links and the original download are included.
Read the full content with GET /receiving/messages/{id}/content and the recipient of the delivery, or parse the original message. Omitted fields are never truncated: they are either complete or empty. The limit keeps payloads below common default request size limits, such as client_max_body_size 1m in nginx. A payload can still exceed it, for example for a message with very many attachments. Allow request bodies of a few megabytes at your endpoint.

​
Messages without parsed content

If the message could not be parsed, the payload has parse_status: failed and a code in parse_warnings. Body fields, headers and attachments are empty; process the message from the original in download. If the parsed content could not be stored within 6 hours of receipt, Talario still delivers the webhook with parse_status: failed and the warning content_unavailable. This warning occurs only in webhooks; the original message is available as usual.

​
Accepting version 2 webhooks

Store the verified payload durably before you answer 2xx; downloading attachments can happen afterwards in a job. Links expire after at most an hour; request new ones through the API. See Process webhooks reliably. Without an API key, your application must download the attachments and the original before the links expire, and when content_omitted is true only the original message is available to it.