EmailCreate

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hail-so/json-schema/hail-so-email-create-schema.json",
  "title": "EmailCreate",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hail-so-openapi.json#/components/schemas/EmailCreate",
  "properties": {
    "recipient_consent": {
      "type": "boolean",
      "title": "Recipient Consent",
      "description": "Attestation that you have obtained the lawful consent required to contact this recipient. Hail does not verify consent itself — you are responsible for a lawful basis under TCPA/ePrivacy/PECR/CAN-SPAM/GDPR as applicable. Rejected (422) if not true."
    },
    "consent_source": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Consent Source",
      "description": "Where/how consent was obtained (e.g. 'signup form', 'prior customer relationship'). Required (non-empty) when message_type is 'marketing'."
    },
    "consent_obtained_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Consent Obtained At",
      "description": "When consent was obtained, if known."
    },
    "message_type": {
      "type": "string",
      "enum": [
        "marketing",
        "informational"
      ],
      "title": "Message Type",
      "description": "'marketing' additionally requires a non-empty consent_source. Use 'informational' for transactional/service communications.",
      "default": "informational"
    },
    "from": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "From",
      "description": "Sender email address. Must be a verified identity on the organization's email domains. Omitted: the org's resolved default sending address, if one exists."
    },
    "from_name": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 256
        },
        {
          "type": "null"
        }
      ],
      "title": "From Name",
      "description": "Display name for the From: header (e.g. 'Acme Billing'). Omitted: no display name."
    },
    "to": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "minItems": 1,
      "title": "To",
      "description": "Recipient email addresses. At least one required."
    },
    "cc": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Cc",
      "description": "CC recipient email addresses."
    },
    "bcc": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Bcc",
      "description": "BCC recipient email addresses."
    },
    "reply_to": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Reply To",
      "description": "Reply-To email address. Omitted: replies go to the From address."
    },
    "subject": {
      "type": "string",
      "maxLength": 998,
      "minLength": 1,
      "title": "Subject",
      "description": "Email subject line."
    },
    "body_text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Body Text",
      "description": "Plain-text body. Either body_text or body_html (or both) is required. A plain-text-only email cannot be tracked for opens or clicks; include body_html to get those events."
    },
    "body_html": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Body Html",
      "description": "HTML body. Either body_text or body_html (or both) is required. Prefer including body_html: open and click tracking only works for emails with an HTML body. Plain-text-only emails still get sent, delivered, and bounce events, but opens and clicks are never tracked."
    },
    "metadata": {
      "additionalProperties": true,
      "type": "object",
      "title": "Metadata",
      "description": "Free-form JSON object attached to the email and echoed back on reads. Not interpreted by Hail. The keys 'forwarded_from', 'forward_headers' and 'system_kind' are reserved for Hail's own queue bookkeeping and are rejected."
    },
    "attachment_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Attachment Ids",
      "description": "Ids returned by POST /email-attachments to attach to this send. Omitted: no attachments."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "recipient_consent",
    "to",
    "subject"
  ]
}