---
title: "Create campaign"
method: POST
path: "/campaigns"
tags: ["Campaigns"]
---

# Create campaign

`POST /campaigns`

## Request

- Base URL: `https://api.omnisend.com/api`
- URL: `https://api.omnisend.com/api/campaigns`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `https://app.omnisend.com/oauth2/token` scopes: `campaigns.write`
  - API key in header `Authorization`

Create a new campaign draft.

**Boosters (`type: booster`):**
- The parent campaign (`boosterSettings.campaignID`) must be a regular email campaign in 'draft' or 'sent' status; 'scheduled' and 'started' parents return 409.
- Each parent campaign supports at most one booster; creating another returns 409. Delete the existing booster first to replace it.
- `sendingSettings` is only allowed when the parent is already sent; for a draft parent provide `boosterSettings.delay` instead (max 240 hours) and the booster is scheduled automatically when the parent sends.

**Scopes:**
`campaigns.write`

**Rate Limiting:**
This endpoint is rate limited to 400 requests per minute.

## Headers

- `Omnisend-Version` string, required

## Request body

- CreateCampaignRequest: Campaign creation request
  - `abTest` CreateABTest: A/B test configuration for campaign creation.
    - `settings` CreateABTestSettings, required: A/B test settings for campaign creation.
      - `decisionTime` CreateABTestDecisionTime: Decision time before selecting a winner. Same shape as booster delay.
        - `amount` integer, required: Number of time units to wait before selecting a winner
        - `unit` 'h' | 'd', required: Time unit: "h" for hours, "d" for days
      - `testSizePercent` integer, required: Percentage of the audience used for testing (10-100). When 100, all recipients get a variant (send-all mode)
      - `winningMetric` 'openRate' | 'clickRate': Metric used to determine the winner. Required unless testSizePercent is 100
    - `variants` CreateABTestVariants, required: A/B test variants object with keys "a" and "b".
      - `a` CreateABTestVariant, required: A/B test variant for creation. Email fields live under `content.email`.
        - `content` CreateABTestVariantContent, required: Variant content grouped by channel for creation.
          - `email` CreateABTestVariantEmail, required: Email content fields for an A/B test variant creation.
            - `preheader` string: Preview text shown in the inbox after the subject line
            - `replyToEmail` string: Reply-to email address for recipient responses. Omit it and replies go to the sender address. Set it only when a specific address is required: it must be an address verified for the brand, and verification status is not exposed here, so an address that is guessed, or copied from another campaign, is rejected.
            - `senderEmail` string: Sender email address. Omit it and the campaign is sent from the sender address configured for the brand. Set it only when a specific address is required: which addresses a brand may send from follows from its sender setup and is not exposed here, so an address that is guessed, or copied from another campaign, is rejected.
            - `senderName` string: Display name of the sender
            - `subject` string, required: Email subject line
            - `templateID` string, required: Template unique identifier. Must reference an existing template.
      - `b` CreateABTestVariant, required: A/B test variant for creation. Email fields live under `content.email`.
        - `content` CreateABTestVariantContent, required: Variant content grouped by channel for creation.
          - `email` CreateABTestVariantEmail, required: Email content fields for an A/B test variant creation.
            - `preheader` string: Preview text shown in the inbox after the subject line
            - `replyToEmail` string: Reply-to email address for recipient responses. Omit it and replies go to the sender address. Set it only when a specific address is required: it must be an address verified for the brand, and verification status is not exposed here, so an address that is guessed, or copied from another campaign, is rejected.
            - `senderEmail` string: Sender email address. Omit it and the campaign is sent from the sender address configured for the brand. Set it only when a specific address is required: which addresses a brand may send from follows from its sender setup and is not exposed here, so an address that is guessed, or copied from another campaign, is rejected.
            - `senderName` string: Display name of the sender
            - `subject` string, required: Email subject line
            - `templateID` string, required: Template unique identifier. Must reference an existing template.
  - `audience` Audience: Campaign audience
    - `excludedCountries` string[]: Countries excluded from the SMS audience, as ISO 3166-1 alpha-2 codes (e.g. "US"). Only applicable to SMS campaigns. Recipients in these countries are not sent to.
    - `excludedSegmentIDs` string[]: Segments to exclude from the audience
    - `includedSegmentIDs` string[]: Segments to include. Empty includes all subscribers
  - `boosterSettings` CreateBoosterSettings: Booster settings for campaign creation
    - `campaignID` string, required: Parent campaign ID to boost
    - `delay` CreateBoosterDelay: Delay settings for booster campaign
      - `amount` integer, required: Amount of time units. Minimum 0 (SMS booster only — means "send together with parent"). Maximum 240 hours (or 10 days)
      - `unit` 'h' | 'd', required: Time unit: "h" for hours, "d" for days
    - `sendTo` 'nonOpeners' | 'nonClickers', required: Which recipients to target: "nonOpeners" or "nonClickers"
  - `channel` 'email' | 'push' | 'sms', required: Campaign message channel
  - `content` CreateContent: Campaign content for creation
    - `email` CreateEmail: Email content for campaign creation
      - `preheader` string: Email preheader text
      - `replyToEmail` string: Reply-to email address for recipient responses. Omit it and replies go to the sender address. Set it only when a specific address is required: it must be an address verified for the brand, and verification status is not exposed here, so an address that is guessed, or copied from another campaign, is rejected.
      - `senderEmail` string: Sender email address. Omit it and the campaign is sent from the sender address configured for the brand. Set it only when a specific address is required: which addresses a brand may send from follows from its sender setup and is not exposed here, so an address that is guessed, or copied from another campaign, is rejected.
      - `senderName` string: Sender display name shown in the recipient's inbox
      - `subject` string: Email subject line
      - `templateID` string, required: Email template unique identifier. Required for regular email campaigns: creation is rejected without it, even when the campaign would be saved as a draft. Booster campaigns are exempt — they may still send content.email (e.g. to override the subject) but do not require a template, inheriting the parent campaign's. A/B-test campaigns carry their template per variant under abTest.variants, not in top-level content. Must reference an existing template. See [Email Templates API](https://api-docs.omnisend.com/reference/email-templates).
    - `sms` CreateSMS: SMS content for campaign creation
      - `compliance` CreateSMSCompliance, required: SMS compliance text settings for creation
        - `stopKeywordText` string, required: STOP keyword text for US/CA recipients
        - `unsubscribeLinkText` string, required: Unsubscribe link text for non-US/CA recipients
      - `imageID` string: Image ID obtained from the Images API. When set, the message is delivered as MMS to US/CA recipients; other countries receive SMS without the image. Image must be JPEG, JPG, PNG, or GIF and not exceed 500 KB
      - `isLinkShorteningEnabled` boolean: Auto-shorten links in message body. Default: true
      - `message` string, required: SMS message body. When sent as SMS, the message (including the appended compliance text and unsubscribe link/keyword) must not exceed 9 SMS segments for either US/CA or other-country recipients. When sent as MMS, the message (including the appended compliance text) must not exceed 1600 characters for US/CA recipients.
  - `language` string: Campaign language locale in xx_XX format. Optional; defaults to en_US when not provided. Must be a supported language when specified
  - `name` string: Campaign name. Required for regular and abTest campaigns (not required for booster)
  - `sendingSettings` CreateSendingSettings: Sending settings for campaign creation
    - `isTZOptimizationEnabled` boolean: Whether timezone optimization is enabled. Only available with immediate or scheduled strategy, and only in email campaigns
    - `optimizeFor` 'opens' | 'clicks' | 'orders': Optimization objective for personalized sends. Required when strategy is "personalized", must not be set otherwise
    - `respectQuietHours` boolean: Whether personalized sends avoid contact-local hours from 22:00 through 06:59. Defaults to true for personalized sends and must not be set for other strategies
    - `scheduledAt` string: Campaign scheduled send time in RFC 3339 format. Required when strategy is "scheduled" or "personalized", must not be set for "immediate". For "scheduled" it must be in the future and within one year from now. For "personalized" only the calendar date in the brand timezone is used, not the time-of-day: the value is normalized to the start of that day in the brand timezone. A date resolving to today starts the STO window at the next whole hour when the campaign is sent; a future date (within one year) starts it at brand-local midnight. Per-contact send times are then chosen within the following 24 hours. Responses store the start as brand-local midnight, which can appear as the previous UTC calendar date
    - `strategy` 'immediate' | 'scheduled' | 'personalized': Sending strategy. Default: immediate. "personalized" enables send time optimization and is only available for regular email campaigns in stores whose plan includes personalized send times and that are eligible for them
  - `type` 'regular' | 'booster' | 'abTest', required: Campaign type. When `type` is `booster`, there are two supported flows: Flow 1 — draft parent + draft booster: Create a draft parent campaign, then create a draft booster for it (set `boosterSettings.delay` to control when it fires). Send the parent; the booster is scheduled automatically based on the configured delay. Flow 2 — already-sent parent: Create and send a parent campaign first. Once it reaches `sent` status, create the booster campaign (omit `boosterSettings.delay`) and use `sendingSettings.scheduledAt` to set the exact send time. Then call the send endpoint on the booster.

## Response `201`

Created campaign

- Campaign: Campaign resource. When `type` is `booster`, the `boosterSettings` field is populated, identifying the parent campaign and the conditions under which the booster targets recipients of that parent.
  - `abTest` ABTest: A/B test configuration. Variants are keyed by "a" and "b"; the parent campaign's `content` field is omitted because variants carry their own content. `result` is populated once a winner is selected and is `null` otherwise.
    - `result` ABTestResult: A/B test result (read-only).
      - `isManuallySelected` boolean: Whether the winner was manually selected (read-only)
      - `selectedAt` string: When the winner was selected (read-only)
      - `winnerVariantID` string: Campaign ID of the winning variant (read-only). Matches variants.a.id or variants.b.id.
    - `settings` ABTestSettings: A/B test settings.
      - `decisionTime` ABTestDecisionTime: Decision time before selecting a winner. Same shape as booster delay.
        - `amount` integer: Amount of time units to wait
        - `unit` 'h' | 'd': Time unit: "h" for hours, "d" for days
      - `testSizePercent` integer: Percentage of audience for the test phase (10-100)
      - `winningMetric` 'openRate' | 'clickRate': Winner determination metric
    - `variants` ABTestVariants: A/B test variants object with keys "a" and "b".
      - `a` ABTestVariant: A/B test variant. Email-specific fields live under `content.email`.
        - `content` ABTestVariantContent: A/B test variant content grouped by channel.
          - `email` ABTestVariantEmail: Email content fields for an A/B test variant.
            - `contentID` string: Email content unique identifier referencing the variant's email design
            - `preheader` string: Preheader text
            - `replyToEmail` string: Reply-to email address
            - `senderEmail` string: Sender email address
            - `senderName` string: Sender display name
            - `subject` string: Email subject line
        - `id` string: Variant campaign ID (read-only). Used for reporting API access.
      - `b` ABTestVariant: A/B test variant. Email-specific fields live under `content.email`.
        - `content` ABTestVariantContent: A/B test variant content grouped by channel.
          - `email` ABTestVariantEmail: Email content fields for an A/B test variant.
            - `contentID` string: Email content unique identifier referencing the variant's email design
            - `preheader` string: Preheader text
            - `replyToEmail` string: Reply-to email address
            - `senderEmail` string: Sender email address
            - `senderName` string: Sender display name
            - `subject` string: Email subject line
        - `id` string: Variant campaign ID (read-only). Used for reporting API access.
  - `audience` Audience: Campaign audience
    - `excludedCountries` string[]: Countries excluded from the SMS audience, as ISO 3166-1 alpha-2 codes (e.g. "US"). Only applicable to SMS campaigns. Recipients in these countries are not sent to.
    - `excludedSegmentIDs` string[]: Segments to exclude from the audience
    - `includedSegmentIDs` string[]: Segments to include. Empty includes all subscribers
  - `boosterSettings` BoosterSettings: Booster-specific settings.
    - `campaignID` string, required: Parent campaign ID this booster follows up on
    - `delay` BoosterDelay: Delay between the parent campaign send and the booster send.
      - `amount` integer: Amount of time units before the booster is sent
      - `unit` 'h' | 'd': Time unit: "h" for hours, "d" for days
    - `sendTo` 'nonOpeners' | 'nonClickers', required: Audience selector. The booster targets recipients of the parent who did NOT perform the implied action (`nonOpeners` did not open; `nonClickers` did not click).
  - `brandID` string: Brand unique identifier (read-only)
  - `channel` 'email' | 'push' | 'sms': Campaign message channel
  - `content` Content: Campaign content
    - `email` Email: Email content
      - `contentID` string: Email content unique identifier referencing the campaign's email design
      - `preheader` string: Email preheader text displayed after the subject line in the recipient's inbox
      - `replyToEmail` string: Reply-to email address for recipient responses
      - `senderEmail` string: Sender email address shown in the recipient's inbox
      - `senderName` string: Sender display name shown in the recipient's inbox
      - `subject` string: Email subject line displayed in the recipient's inbox
    - `sms` SMS: SMS message content
      - `compliance` SMSCompliance: SMS compliance text settings
        - `stopKeywordText` string: STOP keyword text for US/CA recipients. Max 250 chars
        - `unsubscribeLinkText` string: Unsubscribe link text for non-US/CA recipients. Max 250 chars
      - `imageID` string: Image ID obtained from the Images API. When set, the message is delivered as MMS to US/CA recipients; other countries receive SMS without the image. Image must be JPEG, JPG, PNG, or GIF and not exceed 500 KB
      - `isLinkShorteningEnabled` boolean: Auto-shorten links in message body
      - `message` string: SMS message body. When sent as SMS, the message (including the appended compliance text and unsubscribe link/keyword) must not exceed 9 SMS segments for either US/CA or other-country recipients. When sent as MMS, the message (including the appended compliance text) must not exceed 1600 characters for US/CA recipients.
      - `senderName` string: Sender display name. Max 250 chars
  - `createdAt` string: Campaign creation timestamp (read-only)
  - `endedAt` string: Campaign end timestamp (read-only)
  - `id` string: Campaign unique identifier (read-only)
  - `language` string: Campaign language locale in xx_XX format
  - `name` string: Campaign name
  - `sendingSettings` SendingSettings: Campaign sending settings
    - `isTZOptimizationEnabled` boolean: Whether timezone optimization is enabled. Only available with immediate or scheduled strategy, and only in email campaigns
    - `optimizeFor` 'opens' | 'clicks' | 'orders': Optimization objective for personalized sends. Present when strategy is personalized
    - `respectQuietHours` boolean: Whether personalized sends avoid contact-local hours from 22:00 through 06:59
    - `scheduledAt` string: Scheduled send time in RFC 3339 format. Present when strategy is scheduled or personalized
    - `strategy` 'immediate' | 'scheduled' | 'personalized': Sending strategy
  - `startedAt` string: Campaign start timestamp (read-only)
  - `status` 'draft' | 'scheduled' | 'started' | 'sent' | 'error' | 'canceled' | 'paused' | 'onHold' | 'expired' | 'stopped': Campaign status
  - `type` 'regular' | 'abTest' | 'booster': Campaign type
  - `updatedAt` string: Campaign last update timestamp (read-only)
  - `url` string: Link to the campaign in the Omnisend app (read-only): the settings page of a draft campaign (for a booster, the parent campaign's booster page) or the report of a started, sent, canceled, stopped or expired campaign. Omitted for scheduled, paused, on-hold and error campaigns.

## Other responses

- `400`: Request contains invalid or missing fields
- `401`: Authentication is missing or invalid
- `403`: Insufficient permissions for this operation
- `404`: Booster only: parent campaign not found
- `409`: Booster only: booster already exists for this campaign, or parent campaign status does not allow booster operations
- `410`: API version has been retired
- `422`: Campaign channel is not supported, or the store has no verified sender email to use when content.email.senderEmail is omitted
- `429`: Rate limit exceeded
- `500`: Unexpected error occurred

---

[API](https://skmtc.dev/omnisend/apis/campaigns-api.md) - [All operations](https://skmtc.dev/omnisend/apis/campaigns-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnisend/apis/campaigns-api/revisions/fef4d9467305?raw)