---
title: "Schedule new email campaign"
method: POST
path: "/api/v2/email-campaigns/schedule"
tags: ["Scheduled Email Campaigns"]
---

# Schedule new email campaign

`POST /api/v2/email-campaigns/schedule`

<a class="try-sandbox-link" href="https://sandbox.textmagic.com/#/undefined/scheduleEmailCampaign" target="_blank">Try in sandbox</a><br>Creates a new scheduled email campaign that will be sent at a specified time or according to a recurring schedule.

## Request body

- object
  - `emailSenderId` integer, required — Email sender ID from your configured senders.
  - `subject` string, required — Email subject line.
  - `message` string, required — HTML email content.
  - `fromName` string, nullable — Optional custom sender name.
  - `replyToEmail` string, email, nullable — Optional custom reply-to email address.
  - `recipients` object, required — Campaign recipients configuration.
    - `contactIds` integer[], required — Array of contact IDs to send to.
    - `emails` string[], required — Array of email addresses to send to.
    - `groupIds` integer[], required — Array of group IDs to send to.
  - `scheduleParams` object, required — Scheduling configuration for the campaign.
    - `startDateTime` string, date-time, required — When to start sending the campaign (ISO 8601 format).
    - `timezone` string, required — Timezone for the schedule (e.g., "America/New_York").
    - `rrule` string, nullable — RFC 5545 recurrence rule for recurring campaigns.

## Response `201`

Email campaign scheduled successfully.

- ScheduleEmailCampaignResponse
  - `campaign` ScheduledEmailCampaignDetails, required
    - `id` integer, required — Unique scheduled campaign ID.
    - `status` 'scheduled' | 'active' | 'paused' | 'completed' | 'cancelled' | 'failed', required — Current scheduled campaign status.
    - `emailSenderId` integer, nullable — Email sender ID used for this campaign.
    - `startAt` string, date-time, required — Scheduled start timestamp (UTC).
    - `endAt` string, date-time, nullable — End timestamp for recurring campaigns (UTC).
    - `nextSendAt` string, date-time, nullable — Next scheduled send timestamp (UTC).
    - `createdBy` UserPersonalInfo, required
      - `id` integer, required — User ID.
      - `firstName` string, nullable — User's first name.
      - `lastName` string, nullable — User's last name.
      - `avatarUrl` string, nullable — URL to user's avatar image.
      - `email` string, email, nullable — User's email address.
    - `createdAt` string, date-time, required — Campaign creation timestamp.
    - `updatedAt` string, date-time, required — Last update timestamp.
    - `type` 'once' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'follow-up', required — Campaign recurrence type.
    - `fromName` string, nullable — Sender name displayed in recipient's inbox.
    - `fromEmail` string, email, required — Sender email address.
    - `replyToEmail` string, email, required — Reply-to email address.
    - `subject` string, required — Email subject line.
    - `html` string, required — HTML email content.
    - `recipientsCount` integer, required — Number of recipients for this campaign.
    - `sendingTimezone` string, required — Timezone for sending the campaign.
    - `rrule` string, nullable — RFC 5545 recurrence rule for recurring campaigns.
    - `occurrenceSummary` string, nullable — Human-readable schedule description.
  - `cost` number, float, required — Estimated cost for sending this campaign.

## Other responses

- `400` — Bad request - validation errors, invalid schedule, or insufficient balance.
- `401` — Unauthorized request.
- `403` — Forbidden - insufficient permissions (requires ComposeEmail access).

---

[API](https://skmtc.net/textmagic/apis/textmagic-api.md) · [All operations](https://skmtc.net/textmagic/apis/textmagic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/textmagic/textmagic-api/revisions/3e4029d19684/schema)