> ## Documentation Index > Fetch the complete documentation index at: https://bavlio.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create Campaign > Create a new email campaign. Creates a campaign in DRAFT status. Use the launch endpoint to start sending emails. Args: request: Campaign creation request with steps configuration current_user: Authenticated user information service: Campaign service instance Returns: Created campaign response ## OpenAPI ````yaml https://api.bavlio.com/openapi.json post /api/v1/campaigns/ openapi: 3.1.0 info: title: Bavlio API description: >- Outreach automation API — lead enrichment, email campaigns, LinkedIn automation, and AI agent. Full docs at https://docs.bavlio.com. version: 1.0.0 servers: [] security: [] tags: - name: API Keys description: >- Create, list, and revoke API keys for programmatic access. JWT authentication required. - name: credits description: Credit balance, cost estimates, and transaction history. - name: campaigns description: Create, manage, launch, and monitor email campaigns. - name: campaign-personalization description: AI-powered email subject and body personalization for campaigns. - name: email-finder description: Find and verify email addresses for prospects. - name: email-verification description: Validate email addresses and prune invalid entries from datasets. - name: sender-profiles description: Manage sender identity profiles for outreach. - name: sender-profile-chat description: Interactive chat for building sender profiles. - name: templates description: Email template CRUD. - name: suppression description: Do-not-contact suppression list management. - name: datasets description: Lead dataset listing, download, and updates. - name: user-extractions description: Uploaded lead file management and processing. - name: enrichment-chat description: Interactive chat for data enrichment sessions. - name: enrichment-processing description: Batch lead enrichment processing. - name: File Upload (CSV/Excel) description: Upload and preview CSV/Excel lead files. - name: connected-accounts description: LinkedIn account connections via Unipile. - name: linkedin-content description: LinkedIn post creation, scheduling, and management. - name: linkedin-playground description: Direct LinkedIn actions (profile lookup, messaging, engagement). - name: bavimail-proxy description: BaviMail domain, alias, and email management. - name: agent description: Bavi AI agent chat with SSE streaming. - name: notifications description: Notification preferences and delivery. - name: referral description: Referral code management and stats. - name: feedback description: User feedback submission. - name: authentication description: JWT token verification and user info. - name: Google OAuth description: Google OAuth login flow and access tokens. - name: Google Sheets OAuth description: Google Sheets import and access management. - name: stripe description: Stripe checkout, billing portal, and subscription status. JWT only. - name: users description: User quota and usage information. - name: Health description: Health checks and system status. - name: Personalization description: Core lead personalization engine. - name: Session Management description: Enrichment session lifecycle. - name: Session Processing description: Session data processing. - name: webhooks description: Inbound webhook handlers (Stripe, BaviMail, Unipile). paths: /api/v1/campaigns/: post: tags: - campaigns summary: Create Campaign description: |- Create a new email campaign. Creates a campaign in DRAFT status. Use the launch endpoint to start sending emails. Args: request: Campaign creation request with steps configuration current_user: Authenticated user information service: Campaign service instance Returns: Created campaign response operationId: create_campaign_api_v1_campaigns__post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CampaignCreateRequest' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CampaignResponse' '401': description: Unauthorized - Invalid or missing JWT token '403': description: Forbidden - Insufficient permissions '404': description: Campaign not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: CampaignCreateRequest: properties: name: type: string maxLength: 255 minLength: 1 title: Name description: Campaign name description: anyOf: - type: string maxLength: 1000 - type: 'null' title: Description description: Campaign description type: $ref: '#/components/schemas/CampaignType' description: Campaign type (email, linkedin, or mixed) default: email dataset_id: type: string format: uuid title: Dataset Id description: Dataset containing leads alias_ids: anyOf: - items: type: string type: array - type: 'null' title: Alias Ids description: Bavimail alias IDs for sending (required for email campaigns) connected_account_id: anyOf: - type: string format: uuid - type: 'null' title: Connected Account Id description: Connected account ID (required for linkedin campaigns) steps: items: $ref: '#/components/schemas/CampaignStepConfig-Input' type: array maxItems: 10 minItems: 1 title: Steps description: Campaign steps configuration launch_type: $ref: '#/components/schemas/CampaignLaunchType' description: Launch type (immediate or scheduled) default: immediate start_date: anyOf: - type: string format: date-time - type: 'null' title: Start Date description: Scheduled start date (required if launch_type=scheduled) daily_limit: type: integer maximum: 10000 minimum: 1 title: Daily Limit description: Max actions per day default: 500 sending_window_start: type: string format: time title: Sending Window Start description: Daily sending window start (UTC) default: '09:00:00' sending_window_end: type: string format: time title: Sending Window End description: Daily sending window end (UTC) default: '17:00:00' min_interval_seconds: type: integer maximum: 3600 minimum: 60 title: Min Interval Seconds description: Minimum seconds between actions default: 300 timezone: type: string title: Timezone description: Timezone for sending window interpretation default: UTC send_days: items: type: string type: array title: Send Days description: Days of week to send (3-letter lowercase abbreviations) system_prompt: anyOf: - type: string maxLength: 5000 minLength: 100 - type: 'null' title: System Prompt description: >- Campaign-level personalization prompt override. When set, the email pipeline resolver uses this in preference to sender_data.custom_prompt. NULL = fall through to sender-level custom_prompt or DEFAULT. unreviewed_launch_policy: $ref: '#/components/schemas/UnreviewedLaunchPolicy' description: >- Policy applied at scheduled launch time when the campaign uses AI personalization and the user never reviewed drafts in the playground. launch_default = regenerate at send; hold = pause + notify; cancel = revert to draft + notify. default: launch_default type: object required: - name - dataset_id - steps title: CampaignCreateRequest description: Request model for creating a campaign. CampaignResponse: properties: campaign_id: type: string format: uuid title: Campaign Id description: Unique campaign identifier user_id: type: string format: uuid title: User Id description: Owner user ID dataset_id: type: string format: uuid title: Dataset Id description: Associated dataset ID name: type: string title: Name description: Campaign name description: anyOf: - type: string - type: 'null' title: Description description: Campaign description type: type: string title: Type description: Campaign type (email, linkedin, mixed) status: $ref: '#/components/schemas/CampaignStatus' description: Current campaign status launch_type: $ref: '#/components/schemas/CampaignLaunchType' description: Launch type start_date: anyOf: - type: string format: date-time - type: 'null' title: Start Date description: Scheduled start date daily_limit: type: integer title: Daily Limit description: Max actions per day sending_window_start: type: string format: time title: Sending Window Start description: Daily sending window start sending_window_end: type: string format: time title: Sending Window End description: Daily sending window end min_interval_seconds: type: integer title: Min Interval Seconds description: Min seconds between actions timezone: type: string title: Timezone description: Timezone for sending window steps_config: items: $ref: '#/components/schemas/CampaignStepConfig-Output' type: array title: Steps Config description: Steps configuration alias_ids: anyOf: - items: type: string type: array - type: 'null' title: Alias Ids description: Bavimail alias IDs connected_account_id: anyOf: - type: string format: uuid - type: 'null' title: Connected Account Id description: Connected account for LinkedIn send_days: items: type: string type: array title: Send Days description: Days of week to send total_leads: anyOf: - type: integer - type: 'null' title: Total Leads description: Total leads in campaign processed_leads: type: integer title: Processed Leads description: Leads not in pending/active status default: 0 launch_job_id: anyOf: - type: string - type: 'null' title: Launch Job Id description: ARQ job ID for background launch launch_requested_at: anyOf: - type: string format: date-time - type: 'null' title: Launch Requested At description: When launch was requested launch_error: anyOf: - type: string - type: 'null' title: Launch Error description: Error message if launch failed system_prompt: anyOf: - type: string - type: 'null' title: System Prompt description: Campaign-level personalization prompt override (migration 108). unreviewed_launch_policy: $ref: '#/components/schemas/UnreviewedLaunchPolicy' description: >- Policy for scheduled launch without playground review (migration 108). default: launch_default paused_reason: anyOf: - type: string - type: 'null' title: Paused Reason description: >- Reason the campaign is paused, e.g. 'pending_personalization_review' (migration 108). playground_discovery_dismissed_at: anyOf: - type: string format: date-time - type: 'null' title: Playground Discovery Dismissed At description: >- When the owner dismissed the playground discovery banner (migration 108). created_at: type: string format: date-time title: Created At description: Creation timestamp updated_at: type: string format: date-time title: Updated At description: Last update timestamp type: object required: - campaign_id - user_id - dataset_id - name - type - status - launch_type - daily_limit - sending_window_start - sending_window_end - min_interval_seconds - timezone - steps_config - send_days - created_at - updated_at title: CampaignResponse description: Response model for campaign. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError CampaignType: type: string enum: - email - linkedin - mixed title: CampaignType description: Campaign type — determines the execution channel. CampaignStepConfig-Input: properties: step: type: integer minimum: 1 title: Step description: Step number (1-indexed) delay_days: type: integer minimum: 0 title: Delay Days description: Days to wait after previous step (0 for immediate). channel: $ref: '#/components/schemas/CampaignChannel' description: Channel for this step default: email variants: anyOf: - items: $ref: '#/components/schemas/CampaignStepVariant' type: array maxItems: 4 - type: 'null' title: Variants description: Variants for A/B testing (required for email steps) ai_personalization_enabled: type: boolean title: Ai Personalization Enabled description: >- When False, the step is treated as non-personalized by both the Lambda dispatcher (no hold/cancel policy branching) and the playground service (no leads returned for generation). Defaults True for backward compat with legacy campaigns missing this key. default: true track_clicks: type: boolean title: Track Clicks description: Enable click tracking for this step default: false action_type: anyOf: - $ref: '#/components/schemas/LinkedInActionType' - type: 'null' description: LinkedIn action type (required for linkedin steps) message_template: anyOf: - type: string - type: 'null' title: Message Template description: LinkedIn message template with {{variable}} placeholders type: object required: - step - delay_days title: CampaignStepConfig description: |- Configuration for a single step in the campaign sequence. Each step represents one action (email or LinkedIn) in the sequence. CampaignLaunchType: type: string enum: - immediate - scheduled title: CampaignLaunchType description: Campaign launch type values. UnreviewedLaunchPolicy: type: string enum: - launch_default - hold - cancel title: UnreviewedLaunchPolicy description: >- Policy applied when a scheduled AI-personalized campaign fires without review. Mirrors the CHECK constraint on `campaigns.unreviewed_launch_policy` from migration 108. If you add a value here, update the migration too. CampaignStatus: type: string enum: - draft - launching - scheduled - active - draining - paused - completed - failed title: CampaignStatus description: Campaign status values. CampaignStepConfig-Output: properties: step: type: integer minimum: 1 title: Step description: Step number (1-indexed) delay_days: type: integer minimum: 0 title: Delay Days description: Days to wait after previous step (0 for immediate). channel: $ref: '#/components/schemas/CampaignChannel' description: Channel for this step default: email variants: anyOf: - items: $ref: '#/components/schemas/CampaignStepVariant' type: array maxItems: 4 - type: 'null' title: Variants description: Variants for A/B testing (required for email steps) ai_personalization_enabled: type: boolean title: Ai Personalization Enabled description: >- When False, the step is treated as non-personalized by both the Lambda dispatcher (no hold/cancel policy branching) and the playground service (no leads returned for generation). Defaults True for backward compat with legacy campaigns missing this key. default: true track_clicks: type: boolean title: Track Clicks description: Enable click tracking for this step default: false action_type: anyOf: - $ref: '#/components/schemas/LinkedInActionType' - type: 'null' description: LinkedIn action type (required for linkedin steps) message_template: anyOf: - type: string - type: 'null' title: Message Template description: LinkedIn message template with {{variable}} placeholders type: object required: - step - delay_days title: CampaignStepConfig description: |- Configuration for a single step in the campaign sequence. Each step represents one action (email or LinkedIn) in the sequence. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError CampaignChannel: type: string enum: - email - linkedin title: CampaignChannel description: Per-step channel selector (for mixed campaigns). CampaignStepVariant: properties: label: type: string maxLength: 10 minLength: 1 title: Label description: Variant label (e.g., 'A', 'B') weight: type: integer maximum: 100 minimum: 0 title: Weight description: Weight for random selection (0-100) type: $ref: '#/components/schemas/VariantSourceType' description: Content source type template_id: anyOf: - type: string format: uuid - type: 'null' title: Template Id description: Template ID (required if type=TEMPLATE) sender_profile_id: anyOf: - type: string format: uuid - type: 'null' title: Sender Profile Id description: Sender profile ID (required if type=PERSONALIZATION) type: object required: - label - weight - type title: CampaignStepVariant description: |- Configuration for a single variant within a campaign step. A variant represents one possible path for a lead at this step, selected based on weighted randomization during campaign launch. LinkedInActionType: type: string enum: - connection_request - message - follow_up title: LinkedInActionType description: LinkedIn step action types. VariantSourceType: type: string enum: - TEMPLATE - PERSONALIZATION title: VariantSourceType description: Step variant source type. securitySchemes: HTTPBearer: type: http scheme: bearer ````