EmailResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hail-so/json-schema/hail-so-email-response-schema.json",
  "title": "EmailResponse",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hail-so-openapi.json#/components/schemas/EmailResponse",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "title": "Id",
      "description": "Unique identifier for this email."
    },
    "organization_id": {
      "type": "string",
      "format": "uuid",
      "title": "Organization Id",
      "description": "Organization that sent or received this email."
    },
    "email_domain_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ],
      "title": "Email Domain Id",
      "description": "The sending domain used, if from_address belongs to one of the org's configured domains."
    },
    "direction": {
      "type": "string",
      "enum": [
        "outbound",
        "inbound"
      ],
      "title": "Direction",
      "description": "'outbound' for emails Hail sent, 'inbound' for emails received.",
      "default": "outbound"
    },
    "from_address": {
      "type": "string",
      "title": "From Address",
      "description": "Sender email address."
    },
    "from_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "From Name",
      "description": "Display name used on the From: header, when the sender supplied one. Always null on inbound rows."
    },
    "to_addresses": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "To Addresses",
      "description": "Recipient email addresses."
    },
    "cc_addresses": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Cc Addresses",
      "description": "CC recipient email addresses, if any."
    },
    "bcc_addresses": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Bcc Addresses",
      "description": "BCC recipient email addresses, if any."
    },
    "reply_to": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Reply To",
      "description": "Reply-To email address, if set."
    },
    "subject": {
      "type": "string",
      "title": "Subject",
      "description": "Email subject line."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "sent",
        "delivered",
        "failed",
        "bounced",
        "complained",
        "received"
      ],
      "title": "Status",
      "description": "Delivery status: 'queued', 'sent', 'delivered', 'failed', 'bounced', 'complained', or 'received' (inbound emails)."
    },
    "end_reason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "End Reason",
      "description": "Reason delivery failed or bounced, if applicable. Null on success or while pending."
    },
    "provider_message_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Provider Message Id",
      "description": "The email provider's identifier for this message, if assigned."
    },
    "requested_at": {
      "type": "string",
      "format": "date-time",
      "title": "Requested At",
      "description": "When the send was requested, ISO 8601 timestamp."
    },
    "sent_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sent At",
      "description": "When the message was handed to the provider, ISO 8601 timestamp. Null until sent."
    },
    "failed_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Failed At",
      "description": "When the send failed, ISO 8601 timestamp. Null unless it failed."
    },
    "metadata": {
      "additionalProperties": true,
      "type": "object",
      "title": "Metadata",
      "description": "Free-form JSON object attached to the email, as sent on create. Not interpreted by Hail."
    },
    "body_text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Body Text",
      "description": "Plain-text body, if any."
    },
    "body_html": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Body Html",
      "description": "HTML body, if any."
    },
    "message_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Message Id",
      "description": "RFC 5322 Message-ID header. Inbound emails only; null on outbound rows."
    },
    "in_reply_to": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "In Reply To",
      "description": "RFC 5322 In-Reply-To header. Inbound emails only; null on outbound rows."
    },
    "references_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "References Ids",
      "description": "RFC 5322 References header, split into ids. Inbound emails only; null on outbound rows."
    },
    "spam_verdict": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Spam Verdict",
      "description": "Provider spam-scan verdict (e.g. 'PASS'/'FAIL'). Inbound emails only; null on outbound rows."
    },
    "virus_verdict": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Virus Verdict",
      "description": "Provider virus-scan verdict (e.g. 'PASS'/'FAIL'). Inbound emails only; null on outbound rows."
    },
    "dkim_verdict": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Dkim Verdict",
      "description": "Provider DKIM-authentication verdict (e.g. 'PASS'/'FAIL'). Inbound emails only; null on outbound rows."
    },
    "spf_verdict": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Spf Verdict",
      "description": "Provider SPF-authentication verdict (e.g. 'PASS'/'FAIL'). Inbound emails only; null on outbound rows."
    },
    "dmarc_verdict": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Dmarc Verdict",
      "description": "Provider DMARC-authentication verdict (e.g. 'PASS'/'FAIL'). Inbound emails only; null on outbound rows."
    },
    "provider_received_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Provider Received At",
      "description": "When the provider received this email, ISO 8601 timestamp. Inbound emails only."
    },
    "raw_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Raw Url",
      "description": "API endpoint that redirects to the original MIME blob. Inbound emails only; null on outbound rows."
    },
    "attachments": {
      "items": {
        "$ref": "#/$defs/EmailAttachmentResponse"
      },
      "type": "array",
      "title": "Attachments",
      "description": "Inbound MIME attachments on this email. Empty on outbound rows.",
      "default": []
    },
    "last_event_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Last Event At",
      "description": "When the most recent delivery event for this email occurred, ISO 8601 timestamp."
    }
  },
  "type": "object",
  "required": [
    "id",
    "organization_id",
    "email_domain_id",
    "from_address",
    "to_addresses",
    "cc_addresses",
    "bcc_addresses",
    "reply_to",
    "subject",
    "status",
    "end_reason",
    "provider_message_id",
    "requested_at",
    "sent_at",
    "failed_at",
    "body_text",
    "body_html"
  ],
  "$defs": {
    "EmailAttachmentResponse": {
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "title": "Id",
          "description": "Unique identifier for this attachment."
        },
        "filename": {
          "type": "string",
          "title": "Filename",
          "description": "Original filename of the attachment."
        },
        "content_type": {
          "type": "string",
          "title": "Content Type",
          "description": "MIME type of the attachment."
        },
        "size_bytes": {
          "type": "integer",
          "title": "Size Bytes",
          "description": "Size of the attachment in bytes."
        },
        "content_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Content Id",
          "description": "MIME Content-ID, present when this attachment is referenced inline (cid:) from the HTML body. Null otherwise."
        },
        "url": {
          "type": "string",
          "title": "Url",
          "description": "API endpoint that 302-redirects to a presigned download URL for this attachment."
        }
      },
      "type": "object",
      "required": [
        "id",
        "filename",
        "content_type",
        "size_bytes",
        "url"
      ],
      "title": "EmailAttachmentResponse",
      "description": "One inbound MIME attachment as exposed to API consumers.\n\n``url`` is the stable Hail API endpoint that 302-redirects to a\npresigned S3 URL on access — see GET /emails/{id}/attachments/{aid}."
    }
  }
}