Creating Emails

Endpoints

POST /v1/emails
GET  /v1/emails/{emailId}/generations/{generationId}
GET  /v1/emails/{emailId}/content
GET  /v1/emails/{emailId}/generations/{generationId}/content

Emails are the reusable content assets that blasts and triggered flows send. Each email starts as a draft, accumulates versions as you iterate, and must be approved before a blast or flow can use it.

AI generation is asynchronous. Creating with a prompt returns 202 Accepted with a generation_id, and you poll the generation endpoint to track progress. Only one generation can run per email at a time.

Idempotency

POST /v1/emails accepts an optional Idempotency-Key header. Retrying with the same key replays the stored result instead of creating a duplicate email. If a request with the same key is still being processed, the API returns 409 Conflict with error_code: "idempotency_in_progress". The same header works on the editing endpoints.

Create an Email

POST /v1/emails

Request Body

Field	Type	Required	Notes
`name`	`string`	Yes	Internal display name, `1`-`200` characters. Not shown to recipients
`prompt`	`string`	No	AI brief, `1`-`10000` characters. When present, content is generated asynchronously
`template_id`	`string`	No	Seed content and sender defaults from an approved email template
`token_data`	`object`	No	Structured data available to the generation as tokens. Requires `prompt` or `template_id`
`subject`	`string`	No	Maximum `998` characters. Must be set before approval
`preview_text`	`string \| null`	No	Inbox preheader, maximum `200` characters
`from_name`	`string \| null`	No	Maximum `120` characters. Must be set before approval
`from_address`	`string \| null`	No	Must be set before approval; sending requires a verified domain
`reply_to_email`	`string \| null`	No	Must be set before approval

Include prompt to queue an AI generation (202 Accepted). Without a prompt, the email is created immediately (201 Created) — seeded from an approved template when template_id is present, or as a blank draft scaffolded from your workspace branding.

Request Example

curl --request POST \
  --url https://api.tented.ai/v1/emails \
  --header "Authorization: Bearer $TENTED_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Welcome email",
    "prompt": "A warm welcome email for new Acme Analytics signups with a CTA to book a demo",
    "subject": "Welcome to Acme"
  }'

Response Example

202 Accepted

{
  "email_id": "f11ef3cf-8664-4fe5-a261-c5b4d647b7d1",
  "generation_id": "01JZ9GLYFA4L4Y9CBM4H31TT8V",
  "message_id": "01JZ9GLYFA6H2T0N8W1QG64M3E",
  "status": "generating"
}

Create From a Template

Pass template_id to start from an approved email template instead of a prompt or a blank scaffold:

curl --request POST \
  --url https://api.tented.ai/v1/emails \
  --header "Authorization: Bearer $TENTED_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "July newsletter",
    "template_id": "7c3f0a4e-91d2-4a8f-b344-2f6f6f0a1b9d"
  }'

When template_id is present:

The template must exist in the same workspace and be approved
The template’s HTML is copied into the new email
The template’s default_subject, default_preview_text, default_from_name, default_from_address, and default_reply_to_email are inherited as the email’s sender headers

Template-seeded creates without a prompt return 201 Created with the email object.

Start From Your Own HTML

POST /v1/emails does not accept raw HTML directly. To start from your own code, create a blank draft (omit prompt and template_id), then replace its content with POST /v1/emails/{emailId}/save-code — up to 2 MB of HTML. Blasts can also create an inline email seeded from your own html when setting the blast’s email.

Poll a Generation

GET /v1/emails/{emailId}/generations/{generationId}

Generation status moves through generating to completed or failed. Completed generations include the version they produced and paths to their content: 200 OK

{
  "generation_id": "01JZ9GLYFA4L4Y9CBM4H31TT8V",
  "status": "completed",
  "type": "iteration",
  "version": 2,
  "content_path": "/v1/emails/f11ef3cf-8664-4fe5-a261-c5b4d647b7d1/generations/01JZ9GLYFA4L4Y9CBM4H31TT8V/content",
  "plain_text_path": "/v1/emails/f11ef3cf-8664-4fe5-a261-c5b4d647b7d1/generations/01JZ9GLYFA4L4Y9CBM4H31TT8V/plain-text",
  "plain_text_source": "auto",
  "created_at": "2026-07-01T12:00:00.000Z",
  "completed_at": "2026-07-01T12:00:41.000Z"
}

Failed generations return error_code: "generation_failed" and an error_message instead.

Read Content

GET /v1/emails/{emailId}/content
GET /v1/emails/{emailId}/generations/{generationId}/content

Returns the HTML of the latest completed version (or of one specific generation) with a text/html content type — not JSON.

Common Errors

Status	Cause
`400 Bad Request`	Invalid JSON body or field validation failure
`401 Unauthorized`	Missing or invalid bearer token
`404 Not Found`	Email or generation does not exist in the workspace
`409 Conflict`	Same `Idempotency-Key` still processing (`idempotency_in_progress`)

Next: Edit Emails

Iterate with AI, save your own HTML, and manage the plain-text alternative.

Tented API

Tents

Email

Contacts & Lists

Campaigns

Analytics

Endpoints

Idempotency

Create an Email

Request Body

Request Example

Response Example

Create From a Template

Start From Your Own HTML

Poll a Generation

Read Content

Common Errors

Next: Edit Emails

​Endpoints

​Idempotency

​Create an Email

​Request Body

​Request Example

​Response Example

​Create From a Template

​Start From Your Own HTML

​Poll a Generation

​Read Content

​Common Errors

Next: Edit Emails

Endpoints

Idempotency

Create an Email

Request Body

Request Example

Response Example

Create From a Template

Start From Your Own HTML

Poll a Generation

Read Content

Common Errors