Skip to main content

Create Campaign

Create a new campaign in your account.

A campaign is always created as a draft. Only name is required; any other fields you include are applied to the draft in the same request, and you can fill in the rest later with Update Campaign.

Request​

POST /campaigns

Request Body​

ParameterTypeRequiredDescription
namestringYesCampaign name (max 255 characters)
subjectstringNoEmail subject line (max 255 characters)
preheaderstringNoPreview text shown after the subject in the inbox (max 255 characters)
from_namestringNoSender display name (max 255 characters)
reply_tostringNoReply-to email address
from_identitystringNoUUID of a sender identity to send from
list_uuidstringNoUUID of a contact list to use as the audience
segment_uuidstringNoUUID of a contact segment to use as the audience
contentstringNoThe email body, in Markdown (max 65000 characters). See Campaign body for the supported Markdown.
overwritebooleanNoDefaults to false. Not needed when creating a campaign; see Update Campaign for when it applies.

from_identity, list_uuid, and segment_uuid must reference resources that belong to your account; an unknown value returns 422 VALIDATION_ERROR.

The content body accepts a subset of Markdown — headings, bold, italic, links, lists, blockquotes, code blocks, images, and horizontal rules. Tables, strikethrough, task lists, inline `code`, and raw HTML are silently dropped rather than rejected, so stick to the supported subset. See Campaign body for the full list.

Example Request​

curl -X POST "https://email.easy.tools/api/v1/campaigns" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Spring Sale",
    "subject": "Up to 40% off this week",
    "preheader": "Our biggest sale of the season",
    "reply_to": "support@acme.com",
    "content": "## Spring sale\n\nUp to **40% off**. [Shop now](https://acme.com/sale)"
  }'

Example Request (name only)​

curl -X POST "https://email.easy.tools/api/v1/campaigns" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "June Newsletter"
  }'

Response​

Success Response (201 Created)​

The full campaign, including its audience and a readiness report.

{
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Spring Sale",
    "status": "draft",
    "subject": "Up to 40% off this week",
    "preheader": "Our biggest sale of the season",
    "from_name": null,
    "reply_to": "support@acme.com",
    "from_identity": null,
    "from_email": null,
    "content": "## Spring sale\n\nUp to **40% off**. [Shop now](https://acme.com/sale)",
    "content_editable_via_api": true,
    "content_overwrite_required": false,
    "audience": {
      "list_uuid": null,
      "segment_uuid": null
    },
    "readiness": {
      "can_send": false,
      "missing": ["from_name", "sender_email", "audience"]
    },
    "created_at": "2026-06-24T10:00:00Z",
    "updated_at": "2026-06-24T10:00:00Z",
    "last_updated_at": "2026-06-24T10:00:00Z"
  }
}

Response Fields​

The created campaign has the fields described in Get Campaign → Response Fields. A new campaign's status is always draft.

Error Responses​

Conflict Error (409 — Overwrite Required)​

Returned when a content write would overwrite a body whose formatting Markdown can't preserve and overwrite was not true. A brand-new campaign has no existing body, so this does not normally occur on create. See Campaign body.

{
  "error": {
    "code": "CONTENT_OVERWRITE_REQUIRED",
    "message": "This campaign's body contains layout blocks (columns/socials/countdown) that Markdown can't represent; pass overwrite=true to replace it."
  }
}

Validation Error (422 Unprocessable Entity)​

Returned when name is missing, a field is malformed, or a referenced from_identity, list_uuid, or segment_uuid does not belong to your account.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid",
    "details": {
      "from_identity": ["Sender identity not found"]
    }
  }
}