SendEmailRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/groundmail-dev/json-schema/groundmail-dev-send-email-request-schema.json",
  "title": "SendEmailRequest",
  "description": "`subject` is required unless `template` is provided (subject comes from the published template).\nProvide `html` and/or `text`, or `template` (mutually exclusive). React Email is compiled\nclient-side by the Node SDK (`react` option) — do not send `react` to the HTTP API.\n",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/groundmail-dev-openapi.yaml#/components/schemas/SendEmailRequest",
  "type": "object",
  "required": [
    "from",
    "to"
  ],
  "properties": {
    "from": {
      "oneOf": [
        {
          "type": "string",
          "format": "email"
        },
        {
          "type": "object",
          "required": [
            "email"
          ],
          "properties": {
            "email": {
              "type": "string",
              "format": "email"
            },
            "name": {
              "type": "string"
            }
          }
        }
      ]
    },
    "to": {
      "oneOf": [
        {
          "type": "string",
          "format": "email"
        },
        {
          "type": "array",
          "items": {
            "type": "string",
            "format": "email"
          }
        }
      ]
    },
    "subject": {
      "type": "string",
      "description": "Required unless using `template` (optional override when sending with a template)."
    },
    "html": {
      "type": "string"
    },
    "htmlBody": {
      "type": "string",
      "description": "Alias for html"
    },
    "html_body": {
      "type": "string",
      "description": "Alias for html"
    },
    "text": {
      "type": "string"
    },
    "textBody": {
      "type": "string",
      "description": "Alias for text"
    },
    "text_body": {
      "type": "string",
      "description": "Alias for text"
    },
    "plain_body": {
      "type": "string",
      "description": "Alias for text"
    },
    "template": {
      "$ref": "#/$defs/SendTemplateRef"
    },
    "reply_to": {
      "oneOf": [
        {
          "type": "string",
          "format": "email"
        },
        {
          "type": "array",
          "items": {
            "type": "string",
            "format": "email"
          }
        }
      ]
    },
    "replyTo": {
      "oneOf": [
        {
          "type": "string",
          "format": "email"
        },
        {
          "type": "array",
          "items": {
            "type": "string",
            "format": "email"
          }
        }
      ],
      "description": "Alias for reply_to"
    },
    "cc": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "bcc": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "tags": {
      "oneOf": [
        {
          "type": "array",
          "maxItems": 10,
          "items": {
            "$ref": "#/$defs/EmailTag"
          }
        },
        {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        }
      ],
      "description": "Key/value tags stored with the email. Groundmail derives a single tag for delivery metadata."
    },
    "tag": {
      "type": "string",
      "description": "Optional delivery tag override."
    },
    "headers": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Custom headers after server-side safety filtering."
    },
    "attachments": {
      "type": "array",
      "maxItems": 10,
      "description": "Up to 10 files, each up to 10MB decoded. The whole request is at most 20MB, Base64-encoded attachments included (Base64 adds about a third), or the send is refused with 413. Not supported for batch sends or scheduled sends in v1.\n",
      "items": {
        "$ref": "#/$defs/EmailAttachment"
      }
    },
    "scheduled_at": {
      "type": "string",
      "format": "date-time",
      "description": "Schedule delivery for a future ISO 8601 timestamp. Returns status `scheduled`."
    },
    "scheduledAt": {
      "type": "string",
      "format": "date-time",
      "description": "Alias for scheduled_at."
    },
    "unsubscribe": {
      "type": "boolean",
      "description": "Opt in to managed unsubscribe for this send. Injects RFC 8058 `List-Unsubscribe`\nheaders and replaces `{{unsubscribe_url}}` in subject/html/text. When sending with\na template, inherits the template's `unsubscribe_enabled` setting unless overridden here.\n"
    },
    "category": {
      "type": "string",
      "enum": [
        "transactional",
        "product",
        "newsletter"
      ],
      "description": "Optional send-level category override. Defaults to the template's category when sending\nwith a template, otherwise `transactional`. `product` (onboarding, lifecycle and\nnotification email) supports category-scoped opt-out and auto-enables managed\nunsubscribe. Transactional and product email are sent from separate IP pools.\n`newsletter` (opt-in newsletters) is accepted only for approved accounts: it is sent\nfrom its own IPs, separate from transactional and product email, always carries\n`List-Unsubscribe` and one-click unsubscribe (`unsubscribe: false` is a\n`validation_error`), honours category opt-outs, and has its own daily ramp-up limit.\nOn an account that is not approved it fails with 403 `newsletter_not_enabled` and\nnothing is sent.\n"
    },
    "tenant": {
      "type": "string",
      "description": "Send as one of your tenants (its `external_id` or `id`). The send uses that\ntenant's domains, suppression list, sending ramp, daily limit and pause switch.\nReaders who unsubscribe from a tenant's email are suppressed or opted out for\nthat tenant only, so other tenants can still mail them.\nOmit it to send from the account as a whole; a send from a domain a tenant owns\nis that tenant's even without `tenant`. A key limited to one tenant always sends\nas its tenant. On an account without tenants, naming one returns 403\n`tenants_not_enabled`.\n"
    }
  },
  "$defs": {
    "EmailAttachment": {
      "type": "object",
      "required": [
        "name",
        "content_type",
        "data"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Filename sent to the recipient."
        },
        "filename": {
          "type": "string",
          "description": "Alias for name."
        },
        "content_type": {
          "type": "string"
        },
        "contentType": {
          "type": "string",
          "description": "Alias for content_type."
        },
        "data": {
          "type": "string",
          "format": "byte",
          "description": "Base64-encoded attachment content (10MB decoded max; the whole request is at most 20MB)."
        },
        "content": {
          "type": "string",
          "format": "byte",
          "description": "Alias for data (base64 string expected over HTTP)."
        },
        "content_id": {
          "type": "string",
          "description": "Optional Content-ID for inline attachments."
        },
        "contentId": {
          "type": "string",
          "description": "Alias for content_id."
        }
      }
    },
    "EmailTag": {
      "type": "object",
      "required": [
        "name",
        "value"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "value": {
          "type": "string"
        }
      }
    },
    "SendTemplateRef": {
      "type": "object",
      "required": [
        "id"
      ],
      "description": "Reference a published template by UUID or alias. Mutually exclusive with html/text.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Template UUID or alias"
        },
        "variables": {
          "type": "object",
          "additionalProperties": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              }
            ]
          },
          "description": "Values for `{{variable}}` placeholders (HTML-escaped in html body)"
        }
      }
    }
  }
}