MessageCreate

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/conduyt-com/json-schema/conduyt-com-message-create-schema.json",
  "title": "MessageCreate",
  "description": "Conditional request requirements are described in endpoint notes/description: Inbound SMS keywords: an inbound SMS whose body is a STOP keyword blocks the number in `fromNumber` (a per-number opt-out, exactly as a text arriving through the provider; the primary number's STOP also ends the contact's drips and SMS sequences) and a START keyword lifts that number's automatic opt-out, for every caller with communications:create. The keyword changes consent only when `fromNumber` belongs to the contact in `contactId`: its primary phone (country-aware, national or E.164) or a secondary phone (custom fields phone_2 / phone_3); a number shared by several contacts belongs to each. The 201 body's `data` then carries `smsConsent`: { keyword: \"stop\" | \"start\", fromNumber, applied }. applied false with reason \"number_not_on_contact\" means the number is not this contact's: the message is still stored, and no opt-out, opt-in, activity, sequence or drip stop, or consent event is recorded; reason \"number_not_canonicalizable\" means the number could not be read as a phone number to block. A STOP with no `fromNumber` records no per-number opt-out and ends the contact's sequences as an unsubscribe (edit access required); `smsConsent` is absent then, and on every other message. `bodyHtml` may nest elements at most 256 levels deep (template contents included, the same cap as a pasted template); deeper answers 400 with code `html_nesting_too_deep`. Every error answer carries a stable machine-readable `code` (additive; branch on the code, never on the error text or the HTTP status); validation refusals are invalid_request, the catch-all 500 is internal_error (the outcome is unknown), permission and billing refusals are auth_refused (or their own code) and billing_required. The 429 carries code rate_limited; 409 contact_gone and 503 merge_in_progress mean nothing was written (under an Idempotency-Key the key is released, never spent: a retry with the same key runs the request again); a provider rejection is 422 email_send_failed. On an outbound email that is not a draft, metadata.attachments (when present) must be a list of objects whose fileId, when present, is text (the files sent as links; an entry without a fileId is not a file and is ignored); otherwise a 400 naming the entry.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/conduyt-com-openapi.yaml#/components/schemas/MessageCreate",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "contactId",
    "channel",
    "direction",
    "body"
  ],
  "properties": {
    "contactId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "channel": {
      "type": "string",
      "enum": [
        "sms",
        "email"
      ]
    },
    "direction": {
      "type": "string",
      "enum": [
        "inbound",
        "outbound"
      ],
      "description": "An outbound SMS that is not a draft is refused here (400): send it with POST /messages/sms/send."
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "description": "Message body (max 100KB) For an email the body is HTML: HTML nested more than 256 elements deep is refused (400 html_nesting_too_deep). At most 102400 bytes (100 KB) of UTF-8; a larger body is refused."
    },
    "subject": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ]
    },
    "fromNumber": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 30
        },
        {
          "type": "null"
        }
      ]
    },
    "toNumber": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 30
        },
        {
          "type": "null"
        }
      ]
    },
    "fromEmail": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 254,
          "format": "email",
          "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
          "description": "The pattern above is the server's rule (Zod's email check). It accepts a domain label that ends in a hyphen (a@b-.co), which an RFC `format: email` validator such as ajv-formats refuses."
        },
        {
          "type": "null"
        }
      ]
    },
    "toEmail": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 254,
          "format": "email",
          "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
          "description": "The pattern above is the server's rule (Zod's email check). It accepts a domain label that ends in a hyphen (a@b-.co), which an RFC `format: email` validator such as ajv-formats refuses."
        },
        {
          "type": "null"
        }
      ]
    },
    "replyTo": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 254,
          "format": "email",
          "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
          "description": "The pattern above is the server's rule (Zod's email check). It accepts a domain label that ends in a hyphen (a@b-.co), which an RFC `format: email` validator such as ajv-formats refuses."
        },
        {
          "type": "null"
        }
      ]
    },
    "cc": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 254,
          "format": "email",
          "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
          "description": "The pattern above is the server's rule (Zod's email check). It accepts a domain label that ends in a hyphen (a@b-.co), which an RFC `format: email` validator such as ajv-formats refuses."
        },
        {
          "maxItems": 50,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 254,
            "format": "email",
            "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
            "description": "The pattern above is the server's rule (Zod's email check). It accepts a domain label that ends in a hyphen (a@b-.co), which an RFC `format: email` validator such as ajv-formats refuses."
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "bcc": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 254,
          "format": "email",
          "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
          "description": "The pattern above is the server's rule (Zod's email check). It accepts a domain label that ends in a hyphen (a@b-.co), which an RFC `format: email` validator such as ajv-formats refuses."
        },
        {
          "maxItems": 50,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 254,
            "format": "email",
            "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
            "description": "The pattern above is the server's rule (Zod's email check). It accepts a domain label that ends in a hyphen (a@b-.co), which an RFC `format: email` validator such as ajv-formats refuses."
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "bodyHtml": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 102400
        },
        {
          "type": "null"
        }
      ],
      "description": "The email's HTML body HTML nested more than 256 elements deep is refused (400 html_nesting_too_deep)."
    },
    "provider": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 50
        },
        {
          "type": "null"
        }
      ]
    },
    "providerId": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "metadata": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "attachments": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "anyOf": [
                      {
                        "type": "object",
                        "properties": {
                          "fileId": {
                            "description": "Read by the handler from the JSON body (the route declares no schema for its type)."
                          }
                        },
                        "description": "Read by the handler from the JSON body (the route declares no schema for its type)."
                      },
                      {}
                    ]
                  },
                  "description": "Read by the handler from the JSON body (the route declares no schema for its type)."
                },
                {}
              ]
            }
          }
        },
        {}
      ],
      "description": "A JSON object, null or absent; any other kind is refused. At most 100 keys, nested at most 6 levels and at most 32768 bytes once sanitised (strings are trimmed and cut to 10000 characters, arrays to 100 items); a larger or deeper object is refused. Reserved keys are stripped, not stored."
    },
    "status": {
      "type": "string",
      "maxLength": 30
    },
    "scheduledAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
          "description": "The pattern above is the server's rule (Zod's ISO date-time check). It also accepts minute precision without seconds (2026-12-01T10:00Z), which an RFC 3339 `format: date-time` validator refuses; send seconds for portability."
        },
        {
          "type": "null"
        }
      ]
    },
    "templateId": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        {
          "type": "null"
        }
      ],
      "description": "Outbound email composed from an email template (active, this account's; else 404). bodyHtml stays the sender's own base; the template's metadata (subject B, preheader, custom head, footer; the marker in bodyHtml wins over body's) is applied when the email is sent or scheduled."
    },
    "subjectEdited": {
      "type": "boolean",
      "description": "With templateId, a tri-state. true: the subject is the sender's own and is sent verbatim. false: the subject is the template's as inserted, so its A/B subject pick applies. Absent: a supplied subject is sent verbatim; an omitted subject gets the template's A/B pick."
    },
    "signature": {
      "type": "string",
      "enum": [
        "new",
        "reply"
      ],
      "description": "Outbound email only: append the sender's saved email signature (GET /me/email-signature), rendered at send time from the live sources (profile, membership, branding, Company details, booking pages), once, when useInCompose and the matching options.compose flag (newEmails for new, replies for reply) are on. A reply gets it above the quoted history; an earlier signature inside the quoted history never suppresses it. Absent = no signature. 422 signature_too_large when the current sources make the signature too large to render (nothing is sent)."
    }
  }
}