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

POST /api/v1/send

Overview

Implements controller.send in routes/api/v1/send/routes.js:8. The authenticated sender requires SEND.EMAIL, resolves an owner-scoped SMTP profile and optional template, builds safe rendered output, appends campaign opt-out once, submits through Nodemailer, records success, and never returns attachment content or credentials.

Deprecated compatibility paths

• POST /api/send

Use the versioned canonical path for new integrations.

Authentication and access

Security scheme: authToken

Parameters

No operation parameters.

Request body

Source-traced Email JSON command.

application/json

Schema: SendRequest

{
    "configuration": "PRIMARY",
    "name": "PASSWORD.RESET",
    "xml": "<user><email>developer@example.com</email></user>",
    "recipient": "developer@example.com",
    "unsubscribeUrl": "https://app.feradel.com/email/preferences",
    "attachments": [
        {
            "filename": "instructions.pdf",
            "content": "JVBERi0xLjQKZmljdGlvbmFs",
            "encoding": "base64",
            "contentType": "application/pdf"
        }
    ]
}

Example request

cURL

curl --request POST \ \
  --url 'https://email.feradel.com/api/v1/send' \
  --header 'x-auth-token: $FERA_AUTH_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"configuration":"PRIMARY","name":"PASSWORD.RESET","xml":"<user><email>developer@example.com</email></user>","recipient":"developer@example.com","unsubscribeUrl":"https://app.feradel.com/email/preferences","attachments":[{"filename":"instructions.pdf","content":"JVBERi0xLjQKZmljdGlvbmFs","encoding":"base64","contentType":"application/pdf"}]}'

Responses

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

Content type: application/json; schema: SendResult

{
    "success": true,
    "info": {
        "messageId": "<fictional-message@example.test>",
        "accepted": [
            "developer@example.com"
        ]
    },
    "rendered": {
        "template": "PASSWORD.RESET",
        "from": "security@example.com",
        "to": "developer@example.com",
        "subject": "Reset your password",
        "attachments": [
            {
                "filename": "instructions.pdf",
                "cid": null
            }
        ]
    }
}

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"
    }
}

502 SMTP or dependent delivery infrastructure did not accept the message.

Content type: application/json; schema: EmailError

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

Status and retry matrix

Source trace

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