Skip to main content
Mailbay sends webhook requests when an email is received and processed. This document provides a detailed breakdown of the webhook payload structure.

​
Example payload

{
  "email": {
    "receipt": {
      "mailbay_domain": "acme.mailbay.cloud",
      "recipient": "john.doe@acme.mailbay.cloud",
      "sender": "notifications@example.com",
      "spam_score": 0.1,
      "received_timestamp": "2023-08-15T14:22:33.457Z"
    },
    "content": {
      "size": 285680,
      "download_url": "https://mailbay-storage.s3.amazonaws.com/emails/abc123def456?signature=xyz789"
    },
    "headers": {
      "subject": "Monthly System Maintenance Notification",
      "date": "15 Aug 2023 16:22:11 +0200",
      "to": [
        "john.doe@acme.mailbay.cloud"
      ],
      "cc": [
        "Engineering <engineering@example.com>"
      ],
      "bcc": null,
      "from": [
        "System Notifications <notifications@example.com>"
      ],
      "sender": null
    }
  },
  "attachments": [
    {
      "filename": "maintenance-schedule.pdf",
      "size": 156780
    },
    {
      "filename": "backup-procedures.docx",
      "size": 89234
    }
  ],
  "ai_processing": {
    "prompt": "Based on the email content, return a JSON object with the following schema: { \"type\": string, \"scheduled_date\": string (YYYY-MM-DD), \"duration\": string, \"affected_systems\": string[], \"urgency\": \"low\" | \"medium\" | \"high\", \"action_required\": boolean }",
    "result_json": {
      "type": "maintenance_notification",
      "scheduled_date": "2023-08-20",
      "duration": "4 hours",
      "affected_systems": [
        "Database",
        "API Gateway",
        "File Storage"
      ],
      "urgency": "medium",
      "action_required": false
    },
    "result": "{\n  \"type\": \"maintenance_notification\",\n  \"scheduled_date\": \"2023-08-20\",\n  \"duration\": \"4 hours\",\n  \"affected_systems\": [\"Database\", \"API Gateway\", \"File Storage\"],\n  \"urgency\": \"medium\",\n  \"action_required\": false\n}",
    "total_tokens_consumed": 1245,
    "request_tokens_consumed": 1180,
    "response_tokens_consumed": 65
  }
}

​
Schema

​
email Object

FieldTypeDescription
receipt.mailbay_domainstringThe Mailbay email relay that received the email.
receipt.recipientstringThe Mailbay address that received the email.
receipt.senderstringThe sender’s email address.
receipt.spam_scorenumberSpam score assigned to the email. Min 0, Max 1. Lower means the email is less likely to be a spam.
receipt.received_timestampstring (ISO 8601)Timestamp when the email was received.
content.sizenumberSize of the full email content in bytes including all attachments.
content.download_urlstringURL to download the full raw content of the email. For security reasons valid only for 5 minutes.

​
email.headers Object

FieldTypeDescription
subjectstringSubject line of the email.
datestringDate and time as reported by the sender.
toarray”To” recipients.
ccarray or null”CC” recipients.
bccarray or null”BCC” recipients.
fromarrayThe sender in the “From” header.
senderstring or nullThe envelope sender.

​
attachments Array

Each item in the attachments array represents one attachment.
FieldTypeDescription
filenamestringName of the attached file.
sizenumberFile size in bytes.

​
ai_processing Object

FieldTypeDescription
promptstringThe AI prompt used to process the email.
result_jsonobjectParsed structured output as JSON, generated by the AI.
resultstringThe raw AI response if it’s not valid JSON.
total_tokens_consumednumberTotal tokens used during AI processing.
request_tokens_consumednumberTokens used for the input prompt and email content.
response_tokens_consumednumberTokens used for the AI’s response.
⌘I