EmailCampaign

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/politicalcomms-com/json-schema/politicalcomms-com-email-campaign-schema.json",
  "title": "EmailCampaign",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/politicalcomms-com-openapi.json#/components/schemas/EmailCampaign",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "awaiting_test",
        "awaiting_approval",
        "ready",
        "scheduled",
        "compiling",
        "sending",
        "paused",
        "completed",
        "deleted"
      ]
    },
    "sender_identity_id": {
      "type": "string",
      "format": "uuid"
    },
    "list_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      }
    },
    "suppression_list_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      }
    },
    "tracking_domain_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Tracking domain serving this campaign's `/e/*` URLs. `null` means the platform link host."
    },
    "tracking_domain": {
      "type": [
        "object",
        "null"
      ],
      "description": "The resolved tracking domain, returned on the single-campaign read. Links are branded only while `status` is `active`; any other status falls back to the platform link host for the send.",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "domain": {
          "type": "string"
        },
        "status": {
          "type": "string"
        }
      }
    },
    "require_approval": {
      "type": "boolean",
      "description": "Require an approval after the test send before this campaign can schedule or send. Off by default; every campaign still requires a successful test send regardless of this setting."
    },
    "approval_status": {
      "type": "string",
      "enum": [
        "not_required",
        "pending",
        "approved"
      ],
      "description": "`not_required` when `require_approval` is off. `pending` once a current test send exists and approval is outstanding. `approved` once granted. Editing the campaign's content, sender, lists, suppression lists, or template resets a `pending` or `approved` status back to `pending` behind a new required test."
    },
    "last_tested_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the campaign's current test send completed. Null until a test send succeeds, and cleared whenever a later edit invalidates it."
    },
    "refcode": {
      "type": [
        "string",
        "null"
      ],
      "description": "Fundraising refcode appended to donation links for attribution. Generated as `e-` plus eight characters when omitted."
    },
    "source_code": {
      "type": [
        "string",
        "null"
      ]
    },
    "scheduled_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "timezone": {
      "type": [
        "string",
        "null"
      ]
    },
    "audience_count": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Deduplicated, suppression-filtered recipient count."
    },
    "counts": {
      "$ref": "#/$defs/EmailCampaignCounts"
    },
    "pause_reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why the campaign is paused. A deliverability breaker sets this automatically."
    },
    "blocked": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "description": "Returned by the single-campaign read only: the machine-readable reasons this campaign will not schedule yet. Empty when it is ready."
    },
    "started_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "completed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "name",
    "status",
    "sender_identity_id"
  ],
  "additionalProperties": true,
  "$defs": {
    "EmailCampaignCounts": {
      "type": "object",
      "properties": {
        "queued": {
          "type": "integer"
        },
        "sent": {
          "type": "integer"
        },
        "delivered": {
          "type": "integer"
        },
        "bounced": {
          "type": "integer"
        },
        "complained": {
          "type": "integer"
        },
        "unsubscribed": {
          "type": "integer"
        },
        "opened": {
          "type": "integer"
        },
        "clicked": {
          "type": "integer"
        },
        "failed": {
          "type": "integer"
        }
      },
      "additionalProperties": true
    }
  }
}