Email

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/customer-io/main/json-schema/customer-io-create-email-newsletter-schema.json",
  "title": "Email",
  "description": "When you create an email, include `subject` and `body`. Set either `from` or `from_id`, but not both. If you set neither, Customer.io uses your oldest verified sending address.",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/customer-io-newsletters-api-openapi.yml#/components/schemas/createEmailNewsletter",
  "allOf": [
    {
      "type": "object",
      "required": [
        "name",
        "type",
        "recipients"
      ],
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 190,
          "description": "The name of the newsletter."
        },
        "recipients": {
          "type": "object",
          "description": "Filter conditions that define the newsletter's recipients. Combine `segment` and `attribute` conditions with `and`, `or`, and `not` operators.\n",
          "properties": {
            "and": {
              "type": "array",
              "description": "An array of conditions that must all be true.",
              "items": {
                "type": "object"
              }
            },
            "or": {
              "type": "array",
              "description": "An array of conditions where at least one must be true.",
              "items": {
                "type": "object"
              }
            },
            "not": {
              "type": "object",
              "description": "A condition or group of conditions to exclude."
            },
            "segment": {
              "type": "object",
              "description": "A segment condition.",
              "properties": {
                "id": {
                  "type": "integer",
                  "description": "The ID of a segment."
                }
              }
            },
            "attribute": {
              "type": "object",
              "description": "A customer attribute condition.",
              "properties": {
                "field": {
                  "type": "string",
                  "description": "The attribute name."
                },
                "operator": {
                  "type": "string",
                  "description": "The comparison operator.",
                  "enum": [
                    "eq",
                    "exists"
                  ]
                },
                "value": {
                  "type": "string",
                  "description": "The value to compare against. Required when `operator` is `eq`."
                },
                "inverse": {
                  "type": "boolean",
                  "description": "Set to `true` for \"is not equal\" or \"does not exist\"."
                }
              }
            }
          }
        },
        "send_now": {
          "type": "boolean",
          "description": "If `true`, the newsletter is sent immediately after creation. You cannot set both `send_now` and `scheduled_at`."
        },
        "scheduled_at": {
          "type": "integer",
          "format": "unix timestamp",
          "description": "A Unix timestamp indicating when to send the newsletter. The time must be in the future. You cannot set both `send_now` and `scheduled_at`."
        },
        "subscription_topic_id": {
          "type": "integer",
          "description": "The newsletter audience's subscription topic ID. Required when [subscription center](/journeys/channels/subscriptions/center/#enable-sub-center) is enabled; otherwise sends to globally subscribed profiles."
        }
      }
    },
    {
      "type": "object",
      "description": "Optional newsletter rate limiting. If you set `rate_limit_email_rate` or `rate_limit_time_period`, set both; `rate_limit_spread` can be set alone.",
      "properties": {
        "rate_limit_email_rate": {
          "type": "integer",
          "minimum": 1,
          "description": "Maximum number of messages per time period. **NOTE:** Though this states `email_rate`, you can use this for other message channels. Only fixed rate limits are supported, not [daily ramp limits](/journeys/send/broadcasts/newsletters/#daily-ramp).\n"
        },
        "rate_limit_time_period": {
          "type": "integer",
          "enum": [
            60,
            3600,
            86400
          ],
          "description": "Time period in seconds for rate limiting. Must be one of 60 (minute), 3600 (hour), or 86400 (day)."
        },
        "rate_limit_spread": {
          "type": "boolean",
          "description": "When `true`, spreads messages evenly across the time period. Otherwise, it sends as fast as possible up to the limit in each period."
        }
      }
    },
    {
      "type": "object",
      "required": [
        "subject",
        "body"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "The channel type for the newsletter.",
          "enum": [
            "email"
          ]
        },
        "subject": {
          "type": "string",
          "description": "The subject line of the email."
        },
        "preheader_text": {
          "x-scalar-ignore": true,
          "type": "string",
          "description": "[Also known as \"preview text\"](/journeys/channels/email/headers/custom-preheader-text/), this is the small block of text shown in an email inbox next to or underneath the subject line.\n"
        },
        "body": {
          "type": "string",
          "description": "The HTML body content of the email. Use standard HTML/CSS, not syntax unique to Design Studio."
        },
        "body_plain": {
          "type": "string",
          "description": "The plaintext body of the email. If provided, this overwrites the auto-generated plaintext."
        },
        "layout_id": {
          "type": "integer",
          "description": "The ID of the [layout](/journeys/channels/email/layouts/3-layouts-and-customerio/) you want to use for the email. If you don't set one, the email uses your workspace's default layout. Find a layout's ID in its URL."
        },
        "from": {
          "type": "string",
          "description": "The address to send the email from, in the format `Name <email@domain.com>`. You can set `from` or `from_id`, but not both. Use one of the `address` values from [List sender identities](#tag/sender-identities/listSenders)."
        },
        "from_id": {
          "x-scalar-ignore": true,
          "type": "integer",
          "description": "The identifier of the `from` address, commonly known as the \"sender\". Use [List sender identities](#tag/sender-identities/listSenders) to find valid IDs."
        }
      }
    }
  ]
}