`https://lumail.io/api/v1/campaigns`

Create a new email campaign in your organization. The campaign is created with a DRAFT status and can be edited before scheduling or sending.

## Response

- **Success (200 OK)** - Returns the created campaign object.
- **Error (400 Bad Request)** - Validation error or no email sender configured.
- **Error (401 Unauthorized)** - Invalid or missing API token.

## Request Schema

| Field         | Type   | Default     | Description                                            |
| ------------- | ------ | ----------- | ------------------------------------------------------ |
| `subject`     | string | required    | Email subject line                                     |
| `name`        | string | `Untitled`  | Internal name for the campaign                         |
| `preview`     | string | optional    | Preview text shown in email clients                    |
| `content`     | object | boilerplate | Email content in TipTap JSON format                    |
| `contentType` | string | `MAILY`     | Content type: `MAILY`, `PLATE`, or `MARKDOWN`          |
| `senderId`    | string | auto        | Email sender ID (uses default sender if not specified) |
| `replyTo`     | string | optional    | Reply-to email address                                 |

## Response Fields

| Field                     | Type           | Description                                      |
| ------------------------- | -------------- | ------------------------------------------------ |
| `success`                 | boolean        | Indicates if the operation was successful        |
| `campaign`                | object         | The created campaign object                      |
| `campaign.id`             | string         | Unique identifier for the campaign               |
| `campaign.campaignId`     | string         | Same as id (for consistency)                     |
| `campaign.name`           | string         | Name of the campaign                             |
| `campaign.subject`        | string         | Email subject line                               |
| `campaign.preview`        | string or null | Preview text for the email                       |
| `campaign.status`         | string         | Campaign status (always DRAFT for new campaigns) |
| `campaign.contentType`    | string         | Content type: MAILY, PLATE, or MARKDOWN          |
| `campaign.content`        | object         | Email content in TipTap JSON format              |
| `campaign.replyTo`        | string or null | Reply-to email address                           |
| `campaign.senderId`       | string         | Email sender ID                                  |
| `campaign.recipientCount` | number         | Number of recipients (0 for new campaigns)       |
| `campaign.createdAt`      | string         | ISO timestamp when the campaign was created      |
| `campaign.updatedAt`      | string         | ISO timestamp when the campaign was last updated |
| `campaignId`              | string         | Campaign ID at the root level for convenience    |

## Content Format

The `content` field accepts TipTap JSON format. If not provided, a default template is used that includes:

- A "Hello, world!" paragraph
- An unsubscribe link (required for email compliance)

Example content structure:

```json
{
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [{ "type": "text", "text": "Hello, {{name}}!" }]
    }
  ]
}
```

## Usage Example

Use this API endpoint to:

- Create campaigns programmatically from your application
- Set up automated campaign creation workflows
- Build custom campaign management interfaces
- Import campaigns from other email marketing tools

## Related Documentation

- [List Campaigns](/docs/api-reference/api-campaigns-get) - List all campaigns
- [Get Campaign](/docs/api-reference/api-campaign-get) - Get details for a specific campaign
- [Update Campaign](/docs/api-reference/api-campaign-patch) - Update a campaign
- [Delete Campaign](/docs/api-reference/api-campaign-delete) - Delete a campaign
- [Variables](/docs/features/variables) - Use subscriber data in campaigns


## API Reference
**Method:** POST
**Endpoint:** /api/v1/campaigns

### SDK
```ts
import { Lumail } from "lumail";
const lumail = new Lumail({ apiKey: "YOUR_API_TOKEN" });

const { campaign, campaignId } = await lumail.campaigns.create({
  subject: "Welcome to our newsletter!",
  name: "My Newsletter",
  preview: "This is the preview text...",
});
console.log(campaign);
```

### cURL
```bash
curl -X POST https://lumail.io/api/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Newsletter", "subject": "Welcome to our newsletter!"}'
```

### JavaScript
```javascript
const response = await fetch('https://lumail.io/api/v1/campaigns', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'My Newsletter',
    subject: 'Welcome to our newsletter!',
    preview: 'This is the preview text...'
  }),
});

const data = await response.json();
console.log(data);
```

### Python
```python
import requests

url = "https://lumail.io/api/v1/campaigns"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "name": "My Newsletter",
    "subject": "Welcome to our newsletter!",
    "preview": "This is the preview text..."
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data)
```

### Success Response
```json
{
  "success": true,
  "campaign": {
    "id": "cmp_abc123xyz",
    "campaignId": "cmp_abc123xyz",
    "name": "My Newsletter",
    "subject": "Welcome to our newsletter!",
    "preview": "This is the preview text...",
    "status": "DRAFT",
    "contentType": "MAILY",
    "content": {
      "type": "doc",
      "content": [...]
    },
    "replyTo": null,
    "senderId": "snd_xyz789abc",
    "recipientCount": 0,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  },
  "campaignId": "cmp_abc123xyz"
}
```

### Error Response
```json
{
  "message": "No email sender found. Please create an email sender first."
}
```