API reference

Email

One tag: method, path, summary, auth, and scopes. Request and response fields ship in this page — expand a row to read the contract.

Browse docs

Endpoints

POST

/api/v1/email/send Agent Token

Send a single email via SMTP connector

email:send

Description

Sends a single transactional email using an Email (SMTP) connector. Requires a connector with slug 'email-smtp' bound to the service agent with send_email action permitted. Idempotency-Key enables safe retry; the same key and request replay the first result, while changed input returns 409.

Auth

Agent Token

Required Scopes

email:send

Request Body

Field	Type	Required	Description
body	string	Yes	Plain text email body
to	string	Yes	Recipient email address
amount	number	No	Fintech policy amount (top-level PDP input)
html	string	No	Optional HTML email body
subject	string	Yes	Email subject line
environment	string	No	Environment for approval-policy conditions (top-level)
attachments	array<object>	No	Up to 10 inline objects with filename, content_type, and content_base64. URL/path attachments are rejected. Each decoded file is limited to 2 MiB and all decoded files to 5 MiB. Only basename/type/size/SHA-256 metadata is persisted.
connector_id	string	No	Email connector UUID
connector_slug	string	No	Email connector slug (alternative to connector_id)
contains_phi	boolean	No	Healthcare policy input. Hoisted into payload.contains_phi for the same PDP envelope as /gateway/execute.
risk_score	number	No	Risk score for approval-policy conditions (top-level)

Responses

200

Email sent

Response Body

Field	Type	Required	Description
status	string (sent)	Yes	Always sent
action	string (send_email)	Yes	Always send_email
message_id	string	Yes	SMTP message id
connector_id	string	Yes	Connector UUID
connector_slug	string	Yes	Connector slug
duration_ms	integer	Yes	Execution time in milliseconds
trace_id	string	Yes	Runtime trace id

Example

{
  "status": "sent",
  "action": "send_email",
  "message_id": "<[email protected]>",
  "connector_id": "550e8400-e29b-41d4-a716-446655440000",
  "connector_slug": "email-smtp",
  "duration_ms": 245,
  "trace_id": "a1b2c3d4e5f6"
}

400

Problem JSON. Denied, requires_approval, and invalid_connector_type fall through FallbackController as 400 with detail denied, requires_approval, or invalid_connector_type. SMTP/executor failures also use this status.

401

Invalid or missing token

404

Connector not found

422

Validation failed: missing to/subject/body or connector ref, invalid email, or invalid connector UUID

POST

/api/v1/email/bulk Agent Token

Send bulk emails via SMTP connector

email:send

Description

Sends multiple emails to different recipients using an Email (SMTP) connector. Each recipient can have individual to, subject, body, html, and bounded inline attachment fields. Idempotency-Key protects the whole bulk side effect.

Auth

Agent Token

Required Scopes

email:send

Request Body

Field	Type	Required	Description
amount	number	No	Fintech policy amount (top-level PDP input)
environment	string	No	Environment for approval-policy conditions (top-level)
recipients	array<object>	Yes	Array of recipient objects with to, subject, body, html fields
connector_id	string	No	Email connector UUID
connector_slug	string	No	Email connector slug (alternative to connector_id)
contains_phi	boolean	No	Healthcare policy input. Hoisted into payload.contains_phi for the same PDP envelope as /gateway/execute.
risk_score	number	No	Risk score for approval-policy conditions (top-level)

Responses

200

Bulk send finished

Response Body

Field	Type	Required	Description
status	string (completed)	Yes	Always completed
total	integer	Yes	Recipient count
failed	integer	Yes	Failed count
sent	integer	Yes	Delivered count
action	string (send_bulk_email)	Yes	Always send_bulk_email
connector_id	string	Yes	Connector UUID
connector_slug	string	Yes	Connector slug
duration_ms	integer	Yes	Execution time in milliseconds
trace_id	string	Yes	Runtime trace id

Example

{
  "status": "completed",
  "total": 3,
  "failed": 0,
  "sent": 3,
  "action": "send_bulk_email",
  "connector_id": "550e8400-e29b-41d4-a716-446655440000",
  "connector_slug": "email-smtp",
  "duration_ms": 812,
  "trace_id": "a1b2c3d4e5f6"
}

400

Problem JSON. Denied, requires_approval, and invalid_connector_type fall through FallbackController as 400 with detail denied, requires_approval, or invalid_connector_type.

401

Invalid or missing token

404

Connector not found

422

Validation failed: missing recipients or connector ref, or invalid connector UUID