# Create template (/api-reference/templates/createTemplate)

`POST /templates`

Base URL: `https://next-api.useplunk.com`

Create a new email template.

`from` is required and its domain must already be verified for this project, otherwise the request is rejected.

## Request body

- `name`: string (required) — Internal name for the template.
- `description`: string — Optional internal note. Not sent to recipients.
- `subject`: string (required)
- `body`: string (required) — HTML body. Use `{{variable}}` placeholders to interpolate contact data at send time.
- `from`: string (email) (required) — Sender address. Must belong to a domain verified for this project.
- `fromName`: string — Sender display name.
- `replyTo`: string (email)
- `type`: enum ("TRANSACTIONAL" | "MARKETING" | "HEADLESS") — Optional. Defaults to `MARKETING` when omitted.

Example:

```json
{
  "name": "string",
  "subject": "string",
  "body": "string",
  "from": "user@example.com"
}
```

## Responses

### `201` — Template created

- `id`: string
- `name`: string
- `description`: string
- `subject`: string
- `body`: string — HTML content with `{{variable}}` placeholders.
- `from`: string (email) — Sender address. Must belong to a verified domain.
- `fromName`: string
- `replyTo`: string (email)
- `type`: enum ("TRANSACTIONAL" | "MARKETING" | "HEADLESS")
- `projectId`: string
- `createdAt`: string (date-time)
- `updatedAt`: string (date-time)

```json
{
  "id": "string",
  "name": "string",
  "description": "string",
  "subject": "string",
  "body": "string",
  "from": "user@example.com",
  "fromName": "string",
  "replyTo": "user@example.com",
  "type": "TRANSACTIONAL",
  "projectId": "string",
  "createdAt": "2026-08-09T17:56:20.166Z",
  "updatedAt": "2026-08-09T17:56:20.166Z"
}
```

### `400` — A required field (`name`, `subject`, `body`, `from`) is missing.

- `error`: string

```json
{
  "error": "string"
}
```

### `401` — Missing or invalid API key.

- `success`: enum (false)
- `error`: object
  - `code`: string — Machine-readable error code, e.g. `VALIDATION_ERROR`, `INVALID_API_KEY`, `IDEMPOTENCY_KEY_REUSED`.
  - `message`: string
  - `statusCode`: integer
  - `requestId`: string — Correlation ID for this request. Include it when contacting support.
  - `errors`: array<object> — Field-level detail, present on validation failures.
    items:
      - `field`: string — Dot-path of the offending field, e.g. `attachments.0.filename`.
      - `message`: string
      - `code`: string — Validation issue code, e.g. `invalid_type`, `too_big`, `reserved_event`.
      - `received`: object — The value that was received, when available.
  - `details`: object — Additional error context.
  - `suggestion`: string — Hint for fixing the request.
- `timestamp`: string (date-time)

```json
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "statusCode": 0,
    "requestId": "string",
    "errors": [
      {
        "field": "string",
        "message": "string",
        "code": "string",
        "received": null
      }
    ],
    "details": null,
    "suggestion": "string"
  },
  "timestamp": "2026-08-09T17:56:20.166Z"
}
```

### `403` — The sender domain is not registered to this project, or has not completed DNS verification. Add and verify the domain in your project settings first.

- `success`: enum (false)
- `error`: object
  - `code`: string — Machine-readable error code, e.g. `VALIDATION_ERROR`, `INVALID_API_KEY`, `IDEMPOTENCY_KEY_REUSED`.
  - `message`: string
  - `statusCode`: integer
  - `requestId`: string — Correlation ID for this request. Include it when contacting support.
  - `errors`: array<object> — Field-level detail, present on validation failures.
    items:
      - `field`: string — Dot-path of the offending field, e.g. `attachments.0.filename`.
      - `message`: string
      - `code`: string — Validation issue code, e.g. `invalid_type`, `too_big`, `reserved_event`.
      - `received`: object — The value that was received, when available.
  - `details`: object — Additional error context.
  - `suggestion`: string — Hint for fixing the request.
- `timestamp`: string (date-time)

```json
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "statusCode": 0,
    "requestId": "string",
    "errors": [
      {
        "field": "string",
        "message": "string",
        "code": "string",
        "received": null
      }
    ],
    "details": null,
    "suggestion": "string"
  },
  "timestamp": "2026-08-09T17:56:20.166Z"
}
```

## Example request

```bash
curl -X POST 'https://next-api.useplunk.com/templates' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"string","subject":"string","body":"string","from":"user@example.com"}'
```