How can we help you?

Advanced documentation search

Create or update an email template

Product: FeraEmail Topic: API Versions: Applies to all documented versions Current
Written by user
Updated

Audience: Application developers
Editorial status: Published — Source Validated
Product: FeraEmail
Classification: administrative

POST /api/v1/templates

Overview

Implements controller.createOrUpdate in routes/api/v1/template/routes.js:8. The authenticated owner boundary enforces view/edit permission and never returns SMTP passwords; templates and profiles are isolated by instance owner.

Deprecated compatibility paths

  • POST /api/templates

Use the versioned canonical path for new integrations.

Authentication and access

Security scheme: authToken

Control Contract
Authentication authenticated
Authorization The handler requires EDIT.TEMPLATE
Licensing If the instance header identifies a lifecycle-managed FeraEmail tenant, non-Active product state returns 403 before the router executes.
Instance Context The instance header scopes FeraAuth permission checks and owner-scoped SMTP configurations/templates; explicit owner fields are limited by the handler’s lookup rules.
Ownership Configuration and template persistence/lookups are owner-scoped; cross-owner UUID/name lookups do not return a resource.

Parameters

No operation parameters.

Request body

Source-traced Email JSON command.

application/json

Schema: EmailTemplate

{
    "category": "SECURITY",
    "name": "PASSWORD.RESET",
    "from": "security@example.com",
    "replyTo": "support@example.com",
    "subject": "Reset your password",
    "html": "<p>Use the secure reset link.</p>",
    "meta": {
        "version": 1
    }
}

Example request

cURL

curl --request POST \ \
  --url 'https://email.feradel.com/api/v1/templates' \
  --header 'x-auth-token: $FERA_AUTH_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"category":"SECURITY","name":"PASSWORD.RESET","from":"security@example.com","replyTo":"support@example.com","subject":"Reset your password","html":"<p>Use the secure reset link.</p>","meta":{"version":1}}'

Responses

200 The source-traced Email handler completed and returned its profile, template, send, lifecycle, or shared-owner result.

Content type: application/json; schema: EmailResult

{
    "success": true,
    "uuid": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
    "items": [],
    "data": {
        "uuid": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
        "parentUuid": "715c9ebb-0470-11f1-a928-0ed2cd1b87df"
    }
}

400 Validation, sender/recipient, template registration, fields JSON, or payload rules rejected the request.

Content type: application/json; schema: EmailError

{
    "success": false,
    "message": "The email operation could not be completed.",
    "error": {
        "stage": "validation"
    }
}

401 The x-auth-token or lifecycle HMAC is invalid.

Content type: application/json; schema: EmailError

{
    "success": false,
    "message": "The email operation could not be completed.",
    "error": {
        "stage": "validation"
    }
}

403 Send/view/edit, managed-product, owner, or lifecycle sender permission is missing.

Content type: application/json; schema: EmailError

{
    "success": false,
    "message": "The email operation could not be completed.",
    "error": {
        "stage": "validation"
    }
}

404 The owner-scoped configuration, template, or import source was not found.

Content type: application/json; schema: EmailError

{
    "success": false,
    "message": "The email operation could not be completed.",
    "error": {
        "stage": "validation"
    }
}

500 Persistence, template build, SMTP transport, lifecycle, or provisioning failed unexpectedly.

Content type: application/json; schema: EmailError

{
    "success": false,
    "message": "The email operation could not be completed.",
    "error": {
        "stage": "validation"
    }
}

Status and retry matrix

Status Condition Retryable Developer action
200 The source-traced Email handler completed and returned its profile, template, send, lifecycle, or shared-owner result. No Continue with the returned resource or SMTP acceptance result.
400 Validation, sender/recipient, template registration, fields JSON, or payload rules rejected the request. No Correct credential, owner, content, permission, state, or dependency before retrying.
401 The x-auth-token or lifecycle HMAC is invalid. No Correct credential, owner, content, permission, state, or dependency before retrying.
403 Send/view/edit, managed-product, owner, or lifecycle sender permission is missing. No Correct credential, owner, content, permission, state, or dependency before retrying.
404 The owner-scoped configuration, template, or import source was not found. No Correct credential, owner, content, permission, state, or dependency before retrying.
500 Persistence, template build, SMTP transport, lifecycle, or provisioning failed unexpectedly. Yes Correct credential, owner, content, permission, state, or dependency before retrying.

Related operations and events

  • Operation email_get_templates
  • Operation email_post_templatesRIUuid}
  • Operation email_get_templatesNNamedOOwnerFFields}
  • Operation email_get_templatesG
  • Operation email_get_templatesUuid}
  • Operation email_delete_templatesUuid}

Source trace

Repository: feradelinc/feradel.email.api
Branch: agent/catch-up-email-api
Commit: b4278c2d3ef83b95a6cd26c1fd6ec45a0adb99b5
Route: routes/api/v1/template/routes.js
Handler: controller.createOrUpdate
Contract: OpenAPI 3.1, source-traced and publication-validated.