# Templates

Reusable content that steps, broadcasts and transactional emails can copy.

## List templates

`GET /projects/{project_id}/templates`

Newest first, without content; get one template for it.

### Parameters

| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `project_id` | path | string | Required |
| `cursor` | query | string \| null | Optional |
| `limit` | query | integer | Optional, default 50 |

```sh Request
curl "https://sendocado.com/api/v1/projects/$PROJECT_ID/templates" \
  -H "Authorization: Bearer $SENDOCADO_API_KEY"
```

### Response

```json 200
{
  "templates": [
    {
      "id": "29be2u66mr26846p7q9m2i0hz2uep1en",
      "name": "Receipt",
      "subject": "Your Acme receipt for {{ variables.order_number }}",
      "created_at": 1789136000000
    }
  ],
  "next_cursor": null
}
```

### Errors

| Status | Type | Example message |
| --- | --- | --- |
| 400 | `invalid_data` | limit: Too big: expected number to be <=200 |
| 401 | `unauthorized` | Send a valid API key as "Authorization: Bearer sc_…", or sign in. |
| 404 | `project_not_found` | Project not found. |
| 429 | `rate_limited` | Too many requests. Try again in 12 seconds. |

## Create a template

`POST /projects/{project_id}/templates`

Content is html or markdown; text and merge_tags in the response are worked out from it.

### Parameters

| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `project_id` | path | string | Required |

### Body

Send JSON with every field.

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string | Required |
| `subject` | string | Required |
| `preview_text` | string \| null | Required |
| `html` | string \| null | Required |
| `markdown` | string \| null | Required |

```sh Request
curl -X POST "https://sendocado.com/api/v1/projects/$PROJECT_ID/templates" \
  -H "Authorization: Bearer $SENDOCADO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Receipt",
  "subject": "Your Acme receipt for {{ variables.order_number }}",
  "preview_text": null,
  "html": "<p>Thanks for your order, {{ first_name | there }}.</p>\n<p>Order {{ variables.order_number }}: {{ variables.total }}</p>\n",
  "markdown": null
}'
```

### Response

```json 201
{
  "id": "29be2u66mr26846p7q9m2i0hz2uep1en",
  "project_id": "ujzde8gxd6ncf10epf91dhodzdoc9is0",
  "name": "Receipt",
  "subject": "Your Acme receipt for {{ variables.order_number }}",
  "preview_text": null,
  "html": "<p>Thanks for your order, {{ first_name | there }}.</p>\n<p>Order {{ variables.order_number }}: {{ variables.total }}</p>\n",
  "text": "Thanks for your order, {{ first_name | there }}.\n\nOrder {{ variables.order_number }}: {{ variables.total }}",
  "merge_tags": ["first_name", "variables.order_number", "variables.total"],
  "created_at": 1789136000000
}
```

### Errors

| Status | Type | Example message |
| --- | --- | --- |
| 400 | `invalid_data` | Send a JSON request body. |
| 401 | `unauthorized` | Send a valid API key as "Authorization: Bearer sc_…", or sign in. |
| 404 | `project_not_found` | Project not found. |
| 429 | `rate_limited` | Too many requests. Try again in 12 seconds. |

## Get a template

`GET /templates/{template_id}`

The template’s content, with its plain text and merge tags.

### Parameters

| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `template_id` | path | string | Required |

```sh Request
curl "https://sendocado.com/api/v1/templates/$TEMPLATE_ID" \
  -H "Authorization: Bearer $SENDOCADO_API_KEY"
```

### Response

```json 200
{
  "id": "29be2u66mr26846p7q9m2i0hz2uep1en",
  "project_id": "ujzde8gxd6ncf10epf91dhodzdoc9is0",
  "name": "Receipt",
  "subject": "Your Acme receipt for {{ variables.order_number }}",
  "preview_text": null,
  "html": "<p>Thanks for your order, {{ first_name | there }}.</p>\n<p>Order {{ variables.order_number }}: {{ variables.total }}</p>\n",
  "text": "Thanks for your order, {{ first_name | there }}.\n\nOrder {{ variables.order_number }}: {{ variables.total }}",
  "merge_tags": ["first_name", "variables.order_number", "variables.total"],
  "created_at": 1789136000000
}
```

### Errors

| Status | Type | Example message |
| --- | --- | --- |
| 401 | `unauthorized` | Send a valid API key as "Authorization: Bearer sc_…", or sign in. |
| 404 | `template_not_found` | Template not found. |
| 429 | `rate_limited` | Too many requests. Try again in 12 seconds. |

## Update a template

`PUT /templates/{template_id}`

Emails already made from the template keep their own copy of its content.

### Parameters

| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `template_id` | path | string | Required |

### Body

Send JSON with every field.

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string | Required |
| `subject` | string | Required |
| `preview_text` | string \| null | Required |
| `html` | string \| null | Required |
| `markdown` | string \| null | Required |

```sh Request
curl -X PUT "https://sendocado.com/api/v1/templates/$TEMPLATE_ID" \
  -H "Authorization: Bearer $SENDOCADO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Receipt",
  "subject": "Your Acme receipt for {{ variables.order_number }}",
  "preview_text": null,
  "html": "<p>Thanks for your order, {{ first_name | there }}.</p>\n<p>Order {{ variables.order_number }}: {{ variables.total }}</p>\n",
  "markdown": null
}'
```

### Response

```json 200
{
  "id": "29be2u66mr26846p7q9m2i0hz2uep1en",
  "project_id": "ujzde8gxd6ncf10epf91dhodzdoc9is0",
  "name": "Receipt",
  "subject": "Your Acme receipt for {{ variables.order_number }}",
  "preview_text": null,
  "html": "<p>Thanks for your order, {{ first_name | there }}.</p>\n<p>Order {{ variables.order_number }}: {{ variables.total }}</p>\n",
  "text": "Thanks for your order, {{ first_name | there }}.\n\nOrder {{ variables.order_number }}: {{ variables.total }}",
  "merge_tags": ["first_name", "variables.order_number", "variables.total"],
  "created_at": 1789136000000
}
```

### Errors

| Status | Type | Example message |
| --- | --- | --- |
| 400 | `invalid_data` | Send a JSON request body. |
| 401 | `unauthorized` | Send a valid API key as "Authorization: Bearer sc_…", or sign in. |
| 404 | `template_not_found` | Template not found. |
| 429 | `rate_limited` | Too many requests. Try again in 12 seconds. |

## Delete a template

`DELETE /templates/{template_id}`

Emails made from it keep their copy of the content.

### Parameters

| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `template_id` | path | string | Required |

```sh Request
curl -X DELETE "https://sendocado.com/api/v1/templates/$TEMPLATE_ID" \
  -H "Authorization: Bearer $SENDOCADO_API_KEY"
```

### Response

`204` with no body.

### Errors

| Status | Type | Example message |
| --- | --- | --- |
| 401 | `unauthorized` | Send a valid API key as "Authorization: Bearer sc_…", or sign in. |
| 404 | `template_not_found` | Template not found. |
| 429 | `rate_limited` | Too many requests. Try again in 12 seconds. |