How can we help you?

Advanced documentation search

Create or update an SMTP configuration

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/configurations

Overview

Implements controller.createOrUpdate in routes/api/v1/configuration/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/configurations

Use the versioned canonical path for new integrations.

Authentication and access

Security scheme: authToken

Control Contract
Authentication authenticated
Authorization The handler requires EDIT.CONFIGURATION
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: EmailConfiguration

{
    "owner": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
    "name": "PRIMARY",
    "host": "smtp.example.test",
    "port": 587,
    "secure": false,
    "user": "smtp-user",
    "password": "environment-managed-password"
}

Example request

cURL

curl --request POST \ \
  --url 'https://email.feradel.com/api/v1/configurations' \
  --header 'x-auth-token: $FERA_AUTH_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"owner":"715c9ebb-0470-11f1-a928-0ed2cd1b87df","name":"PRIMARY","host":"smtp.example.test","port":587,"secure":false,"user":"smtp-user","password":"environment-managed-password"}'

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_configurations
  • Operation email_get_configurationsNName}
  • Operation email_delete_configurationsUuid}

Source trace

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