POST /v1/brands/{brand_id}/email-templates

Create an email template

scope write:outreach cost 1 RU idempotent required

Save an email template for campaigns and sequence steps. Placeholders filled per contact: {{first_name}}, {{name}}, {{email}}, {{company}}, {{brand_name}}, and from the cited page a contact was added with {{page_url}}, {{page_title}}, {{role}}. Requires the editor role and the brand owner on Pro.

Path parameters

brand_id string required

Brand UUID.

Query parameters

dry_run boolean optional

Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns 200 with a dry_run object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns 422.

default: false

Header parameters

Idempotency-Key string required

Required with an API key, else 400 idempotency_key_required: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with dry_run=true.

Request body

application/json required

Type: EmailTemplateCreate

body string required

HTML body. Placeholders filled per contact: {{first_name}}, {{name}}, {{email}}, {{company}}, {{brand_name}}, and from the cited page a contact was added with {{page_url}}, {{page_title}}, {{role}}.

min length: 1 · max length: 50000
name string required

Name.

min length: 1 · max length: 200
subject string required

Subject line. Placeholders filled per contact: {{first_name}}, {{name}}, {{email}}, {{company}}, {{brand_name}}, and from the cited page a contact was added with {{page_url}}, {{page_title}}, {{role}}.

min length: 1 · max length: 500
template_type enum required

request_backlink, request_inclusion, build_relationship, follow_up or pitch.
body_text string (nullable) nullable

Plain-text body.
is_default boolean

Make it the default template of its type.

default: `false`

Example payload

{
  "body": "<p>Hi {{first_name}}, I read {{page_url}} and thought the Allbirds Tree Runner fits it.</p>",
  "is_default": false,
  "name": "Best running shoes pitch",
  "subject": "{{first_name}}, a shoe for {{page_title}}",
  "template_type": "request_inclusion"
}

Responses

Created an email template application/json

Type: EmailTemplate

body string required

HTML body. Placeholders filled per contact: {{first_name}}, {{name}}, {{email}}, {{company}}, {{brand_name}}, and from the cited page a contact was added with {{page_url}}, {{page_title}}, {{role}}.
brand_id string required

Owning brand id.
id string required

Template id.
is_default boolean required

The default template of its type.
name string required

Name.
subject string required

Subject line. Placeholders filled per contact: {{first_name}}, {{name}}, {{email}}, {{company}}, {{brand_name}}, and from the cited page a contact was added with {{page_url}}, {{page_title}}, {{role}}.
template_type enum required

What the email asks for: request_backlink, request_inclusion, build_relationship, follow_up or pitch.
body_text string (nullable) nullable

Plain-text body.
created_at string (nullable) nullable

When the template was created.

format: `date-time`
object string

default: `email_template`
updated_at string (nullable) nullable

Last change.

format: `date-time`
variables array of string

Placeholders the template uses.

Example response

{
  "body": "<p>Hi {{first_name}}, I read {{page_url}} and thought the Allbirds Tree Runner fits it.</p>",
  "body_text": "Hi {{first_name}}, I read {{page_url}} and thought the Allbirds Tree Runner fits it.",
  "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
  "created_at": "2026-09-20T10:00:00+00:00",
  "id": "2b3c4d5e-6f70-4a1b-8c2d-3e4f5a6b7c8d",
  "is_default": false,
  "name": "Best running shoes pitch",
  "object": "email_template",
  "subject": "{{first_name}}, a shoe for {{page_title}}",
  "template_type": "request_inclusion",
  "updated_at": "2026-09-20T10:00:00+00:00",
  "variables": [
    "first_name",
    "page_title",
    "page_url"
  ]
}

Request validation failed application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Missing or invalid credentials application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

You do not have permission to access this resource application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Resource not found application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Resource conflict application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "conflict",
    "message": "Resource conflict"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Request body did not match the expected schema application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "body_validation_error",
    "message": "Request body did not match the expected schema"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Per-minute rate limit exceeded application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-minute rate limit exceeded"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

An unexpected error occurred application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Service temporarily unavailable, please retry application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable, please retry"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Request example

curl --request POST \
  --url 'https://api.rankprompt.com/v1/brands/your_brand_id_here/email-templates?dry_run=false' \
  --header 'Authorization: Bearer rp_live_<YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <UNIQUE_KEY>' \
  --data '{
  "body": "<p>Hi {{first_name}}, I read {{page_url}} and thought the Allbirds Tree Runner fits it.</p>",
  "is_default": false,
  "name": "Best running shoes pitch",
  "subject": "{{first_name}}, a shoe for {{page_title}}",
  "template_type": "request_inclusion"
}'

const fetch = require('node-fetch');

const url = 'https://api.rankprompt.com/v1/brands/your_brand_id_here/email-templates?dry_run=false';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer rp_live_<YOUR_API_KEY>',
    'Idempotency-Key': '<UNIQUE_KEY>',
    'Content-Type': 'application/json'
  },
  body: '{"body":"<p>Hi {{first_name}}, I read {{page_url}} and thought the Allbirds Tree Runner fits it.</p>","is_default":false,"name":"Best running shoes pitch","subject":"{{first_name}}, a shoe for {{page_title}}","template_type":"request_inclusion"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://api.rankprompt.com/v1/brands/your_brand_id_here/email-templates"

querystring = {"dry_run":"false"}

payload = {
    "body": "<p>Hi {{first_name}}, I read {{page_url}} and thought the Allbirds Tree Runner fits it.</p>",
    "is_default": False,
    "name": "Best running shoes pitch",
    "subject": "{{first_name}}, a shoe for {{page_title}}",
    "template_type": "request_inclusion"
}
headers = {
    "Authorization": "Bearer rp_live_<YOUR_API_KEY>",
    "Idempotency-Key": "<UNIQUE_KEY>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers, params=querystring)

print(response.json())