---
title: "Send email campaign"
method: POST
path: "/api/v2/email-campaigns"
tags: ["Email Campaigns"]
---

# Send email campaign

`POST /api/v2/email-campaigns`

<a class="try-sandbox-link" href="https://sandbox.textmagic.com/#/Email%20Campaigns/createEmailCampaign" target="_blank">Try in sandbox</a><br>Creates a new email campaign and sends it to the specified recipients.

This endpoint allows you to create and immediately send an email marketing campaign to your contacts, groups, or direct email addresses. The campaign will be processed asynchronously, and you'll receive a campaign object with tracking information.

## Request Requirements

- **Email Sender ID**: Must be a valid, configured email sender from your account
- **Recipients**: At least one recipient type must be specified (contacts, groups, or emails)
- **Content**: Subject and HTML message content are required
- **Balance**: Sufficient account balance for the estimated campaign cost

## Recipient Types

You can target multiple recipient types in a single campaign:

- **Contact IDs**: Send to specific contacts from your contact list
- **Group IDs**: Send to all contacts within specified groups  
- **Direct Emails**: Send to email addresses not in your contact list

## Content Guidelines

- **Subject**: Maximum 998 characters, should be engaging and relevant
- **Message**: HTML content supported, including images, links, and formatting
- **From Name**: Optional custom sender name (max 500 characters)
- **Reply-To**: Optional custom reply-to email address

## Cost and Balance

The API automatically calculates campaign costs based on:
- Total number of unique recipients across all specified groups, contacts, and emails
- Your account's email pricing tier
- Any additional features or premium content

If your account balance is insufficient, the request will be rejected with a low balance error.

## Response Information

Successful campaigns return:
- Campaign ID for tracking and analytics
- Current campaign status and progress
- Cost breakdown and recipient counts
- Sender information and content preview
- Statistical totals and engagement metrics

## Error Scenarios

Common error conditions include:
- **Validation Errors**: Invalid email addresses, missing required fields, or content that exceeds limits
- **Insufficient Balance**: Account balance too low for campaign cost
- **Invalid Recipients**: Non-existent contact/group IDs or invalid email formats
- **Sender Configuration**: Invalid or unconfigured email sender ID
- **No Recipients**: All recipient arrays are empty or invalid

## 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.

## Response `201`

Email campaign created successfully.

- CreateEmailCampaignResponse
  - `id` integer, required — Unique campaign ID.
  - `status` 'idle' | 'sent' | 'in_progress' | 'failed' | 'delivered' | 'rejected' | 'error' | 'scheduledError', required — Current campaign status.
  - `emailSenderId` integer, nullable — Email sender ID used for this campaign.
  - `startAt` string, date-time, required — Campaign start timestamp.
  - `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.
  - `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.
  - `cost` number, float, required — Total campaign cost.
  - `totals` EmailCampaignStatisticTotals, required
    - `recipients` integer, required — Total number of recipients.
    - `delivered` integer, required — Number of emails delivered.
    - `rejected` integer, required — Number of emails rejected.
    - `failed` integer, required — Number of emails failed to send.
    - `opened` integer, required — Number of emails opened.
    - `clicked` integer, required — Number of emails with clicks.
    - `spamReports` integer, required — Number of spam reports.
    - `unsubscribed` integer, required — Number of unsubscribes.
  - `outboundEmail` OutboundEmailResponse
    - `id` integer, required — Outbound email ID.
    - `sendTime` string, date-time, required — Email send timestamp.
    - `fromName` string, nullable — Sender name.
    - `fromEmail` string, email, required — Sender email address.
    - `replyToEmail` string, email, required — Reply-to email address.
    - `recipientFullName` string, nullable — Recipient's full name.
    - `recipientEmail` string, email, nullable — Recipient's email address.
    - `emailSubject` string, required — Email subject line.
    - `emailContent` string, required — HTML email content.
    - `source` 'emailCampaign' | 'ticket', required — Source of the outbound email.
    - `status` 'pending' | 'sent' | 'delivered' | 'rejected' | 'failed' | 'opened' | 'clicked' | 'unsubscribed' | 'spam', required — Current email status.
    - `cost` number, float, required — Cost of sending this email.
    - `statusReason` string, nullable — Detailed status reason.
    - `contactId` integer, nullable — Associated contact ID.
    - `initiatorId` integer, required — ID of user who initiated the email.
  - `failedReason` 'lowBalance' | 'noRecipients' | 'noEmailSender' | 'unhandled', nullable — Reason for campaign failure if applicable.

## Other responses

- `400` — Bad request - validation errors 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)