POST/api/v1/projects/{project_id}/templates/{template_id}/test-send

`send_test_email`

Sends a message template as a test to a few addresses through the project’s transport: rendered as preview_template renders it with sample_attributes (with none, every attribute is the text sample), from the project’s settings.from_email, the subject prefixed [TEST] , with the header X-Postwind-Test: 1.

Call it: to see a template in a real mailbox before a campaign; each call sends again (there is no idempotency in MCP).
Needs: an admin key with project_id, or a project key with scope send (its own project; the argument is ignored), a project that is not deleted, a message template (a partial is validation_failed on template_id), 1 to 10 valid addresses in to (validation_failed, to or to.<index>), and, as precondition_failed: a settings.from_email on the project and a transport this node can send through (transport_unavailable; get_server_info lists them in available_transports). An address in the project’s suppression list is not sent to.
Returns: transport, from_email, subject and results, one per distinct address (email, outcome: accepted, deferred, rejected, suppressed or failed, message_id, smtp_code, smtp_text, stage), the same as POST /api/v1/projects/{project_id}/templates/{template_id}/test-send.

Arguments

object
template_idstring · uuidrequired

The message template’s id.
toarray of stringrequired

1 to 10 addresses to send the test message to.

example ["me@example.com"]
project_idstring · uuid | null

The template’s project. An admin key must pass it; a project key’s own project is used and this is ignored.
sample_attributesmap of string → string | number | boolean | null

Attributes to render with, as a subscriber’s (string, number or boolean values); without them every attribute is the text sample.

No other arguments are accepted.

Result

The result comes back as structuredContent, with the same JSON as a text block.

object · all fields required
from_emailstring

The sender: the project’s settings.from_email.
resultsarray of TestSendResultOutput

One per distinct address, in the order of the request.
6 fields
- TestSendResultOutput object · all fields required
- emailstring
  
  The address, normalized.
- message_idstring | null
  
  The message’s Message-ID, without angle brackets; null when it was not sent (suppressed).
- outcomeTestSendOutcomeOutput
  
  How the test message to one address went.
  
  accepted The recipient’s server took it.
  
  deferred A temporary refusal (4xx); a test message is not tried again.
  
  rejected A permanent refusal (5xx) at stage.
  
  suppressed The address is in the project’s suppression list: not sent.
  
  failed The transport could not attempt it; the reason is in the node’s log.
- smtp_codeinteger · uint16 | null
  
  The reply code of a refusal (deferred, rejected); otherwise null.
  
  0–65535
- smtp_textstring | null
  
  The reply text of a refusal (deferred, rejected); otherwise null.
- stageRejectStageOutput | null
  
  The stage of a rejected; otherwise null.
  - connect
  - rcpt
  - data
subjectstring

The subject every message carries: [TEST] and the rendered one.
transportstring

The transport the messages went through: direct, relay:<name>.

Definitions

RejectStageOutput

The session stage a refusal happened at.

string · enum

connect
rcpt
data

TestSendOutcomeOutput

How the test message to one address went.

string · enum

accepted The recipient’s server took it.

deferred A temporary refusal (4xx); a test message is not tried again.

rejected A permanent refusal (5xx) at stage.

suppressed The address is in the project’s suppression list: not sent.

failed The transport could not attempt it; the reason is in the node’s log.

TestSendResultOutput

The test message to one address.

object · all fields required
emailstring

The address, normalized.
message_idstring | null

The message’s Message-ID, without angle brackets; null when it was not sent (suppressed).
outcomeTestSendOutcomeOutput

How the test message to one address went.

accepted The recipient’s server took it.

deferred A temporary refusal (4xx); a test message is not tried again.

rejected A permanent refusal (5xx) at stage.

suppressed The address is in the project’s suppression list: not sent.

failed The transport could not attempt it; the reason is in the node’s log.
smtp_codeinteger · uint16 | null

The reply code of a refusal (deferred, rejected); otherwise null.

0–65535
smtp_textstring | null

The reply text of a refusal (deferred, rejected); otherwise null.
stageRejectStageOutput | null

The stage of a rejected; otherwise null.
- connect
- rcpt
- data

Errors

A failed call answers isError: true with a code from the same table as the HTTP API, and detail. How tools report errors

HTTP API

The same operation over HTTP: POST /api/v1/projects/{project_id}/templates/{template_id}/test-send