SendEmailRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/e2a-dev/json-schema/e2a-dev-send-email-request-schema.json",
  "title": "SendEmailRequest",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/e2a-dev-api-openapi.yml#/components/schemas/SendEmailRequest",
  "additionalProperties": false,
  "properties": {
    "attachments": {
      "description": "File attachments (base64 in each item's data). Limits: at most 10 attachments, each ≤ 10 MiB decoded, and ≤ 25 MiB decoded combined. Exceeding the count → 400 invalid_request; exceeding a size → 413 payload_too_large.",
      "items": {
        "$ref": "#/$defs/Attachment"
      },
      "type": "array"
    },
    "bcc": {
      "description": "Bcc recipients. The message is limited to 50 recipients across to, cc, and bcc combined. Each recipient string (display name + address combined) is limited to 320 characters. The address itself must also fit SMTP's mailbox octet limits — local part at most 64 octets and the whole addr-spec at most 254 octets, counted in UTF-8 BYTES rather than characters — or the request is rejected with 400 invalid_recipient. A long plus-addressed local part is the usual way to exceed this.",
      "items": {
        "maxLength": 320,
        "type": "string"
      },
      "type": "array"
    },
    "cc": {
      "description": "Cc recipients. The message is limited to 50 recipients across to, cc, and bcc combined. Each recipient string (display name + address combined) is limited to 320 characters. The address itself must also fit SMTP's mailbox octet limits — local part at most 64 octets and the whole addr-spec at most 254 octets, counted in UTF-8 BYTES rather than characters — or the request is rejected with 400 invalid_recipient. A long plus-addressed local part is the usual way to exceed this.",
      "items": {
        "maxLength": 320,
        "type": "string"
      },
      "type": "array"
    },
    "conversation_id": {
      "description": "Caller-assigned application conversation/grouping id. This value is independent of email thread topology. At most 200 characters — deliberately the same cap as the webhook conversation_ids filter-value limit and the message-list conversation_id filter limit (both 200), so an accepted conversation_id is never too long to filter by. Must not contain CR or LF.",
      "maxLength": 200,
      "type": "string"
    },
    "html": {
      "description": "Literal HTML body. Mutually exclusive with template_id/template_alias.",
      "maxLength": 1048576,
      "type": "string"
    },
    "reply_to": {
      "description": "Sets the Reply-To header — where replies to this message are directed. Either a single RFC 5322 address (optionally with a display name, e.g. \"Support <support@acme.com>\") or an array of up to 5 such addresses to direct replies to several destinations. Each address string is at most 320 characters (display name + address combined), and each address must fit SMTP's mailbox octet limits (local part at most 64 octets, whole addr-spec at most 254 octets, counted in UTF-8 bytes) — a violation is 400 invalid_request. Defaults to the sending agent's own address.",
      "oneOf": [
        {
          "maxLength": 320,
          "type": "string"
        },
        {
          "items": {
            "maxLength": 320,
            "type": "string"
          },
          "maxItems": 5,
          "type": "array"
        }
      ]
    },
    "send_at": {
      "description": "Beta: scheduled sending may change before it is declared stable. Optional scheduled-send time (RFC 3339 with a UTC offset). When set to a future instant the message is accepted immediately and returns status=scheduled; it is submitted to the provider at approximately this time. Treat it as \"not before\" — accurate to within the scheduler's poll interval (seconds), not exact-to-the-millisecond, and actual delivery can be later under provider retry/outage. A value at or before now sends immediately (identical to omitting it). Must be no more than 90 days ahead (over → 400 invalid_request). A future send_at whose only recipient is the sending agent's own address returns 400 invalid_request because self-delivery is an immediate loopback with no scheduled arm — this holds even when the message would otherwise be held for review. Scheduling survives a review hold: if the message is held, send_at is preserved on the pending_review message (surfaced there as scheduled_at) and re-armed on approval — the message is then submitted at send_at if that instant is still in the future, or immediately if it has already passed. Moving the message to trash before provider submission starts prevents submission; if submission already has a fresh lease, delete returns 409 send_in_progress. Restoring before send_at re-arms it; restoring at or after send_at returns it live with delivery_status=failed and leaves the send canceled.",
      "format": "date-time",
      "type": "string",
      "x-stability-level": "beta"
    },
    "subject": {
      "description": "Literal subject. Required unless a template reference is used (mutually exclusive with template_id/template_alias).",
      "maxLength": 2000,
      "type": "string"
    },
    "template_alias": {
      "description": "Send using a stored template resolved by its per-user alias. Mutually exclusive with template_id and with literal subject/text/html. Beta: templates are unstable — their shape may change before they are declared stable.",
      "type": "string",
      "x-stability-level": "beta"
    },
    "template_data": {
      "additionalProperties": {},
      "description": "Variables for the referenced template ({{name}}, dot paths into nested objects). Missing variables render as empty strings. Beta: templates are unstable — their shape may change before they are declared stable.",
      "type": "object",
      "x-stability-level": "beta"
    },
    "template_id": {
      "description": "Send using a stored template (rendered server-side, before any review hold). Mutually exclusive with template_alias and with literal subject/text/html. Beta: templates are unstable — their shape may change before they are declared stable.",
      "type": "string",
      "x-stability-level": "beta"
    },
    "text": {
      "description": "Literal plain-text body. Required unless a template reference is used (mutually exclusive with template_id/template_alias).",
      "maxLength": 1048576,
      "type": "string"
    },
    "to": {
      "description": "Primary recipients. The message is limited to 50 recipients across to, cc, and bcc combined. Each recipient string (display name + address combined) is limited to 320 characters. The address itself must also fit SMTP's mailbox octet limits — local part at most 64 octets and the whole addr-spec at most 254 octets, counted in UTF-8 BYTES rather than characters — or the request is rejected with 400 invalid_recipient. A long plus-addressed local part is the usual way to exceed this.",
      "items": {
        "maxLength": 320,
        "type": "string"
      },
      "type": "array"
    },
    "unsubscribe": {
      "$ref": "#/$defs/UnsubscribeOptions",
      "description": "Beta: opts this message into e2a-managed unsubscribe handling. This field may change before it is declared stable.",
      "x-stability-level": "beta"
    }
  },
  "required": [
    "to"
  ],
  "type": "object",
  "$defs": {
    "Attachment": {
      "additionalProperties": false,
      "properties": {
        "content_type": {
          "type": "string"
        },
        "data": {
          "description": "Base64-encoded file content. Each attachment must be ≤ 10 MiB decoded; a message may carry at most 10 attachments totaling ≤ 25 MiB decoded.",
          "type": "string"
        },
        "filename": {
          "description": "Attachment filename. Maximum 1024 UTF-8 bytes; longer names are rejected as invalid_attachment.",
          "type": "string"
        }
      },
      "required": [
        "filename",
        "content_type",
        "data"
      ],
      "type": "object"
    },
    "UnsubscribeOptions": {
      "additionalProperties": false,
      "description": "Beta: per-message opt-in to e2a-managed unsubscribe handling. This schema may change before it is declared stable.",
      "properties": {
        "mode": {
          "description": "Beta: managed requests e2a-hosted unsubscribe handling. This option may change before it is declared stable.",
          "enum": [
            "managed"
          ],
          "type": "string"
        }
      },
      "required": [
        "mode"
      ],
      "type": "object",
      "x-stability-level": "beta"
    }
  }
}