Postwind Pre-release Download
Docs menu Send a test message

Generated from Postwind commit a19b2e4 OpenAPI 0.1.0 synced

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

Needs scope: sendIdempotency-KeyMCP tool: send_test_email operationId send_test_email

Send a test message

Renders the template’s latest version as the preview does with sample_attributes (or sample values) and sends it to each address of to through the project’s transport: from the project’s settings.from_email (and from_name, reply_to), the subject prefixed [TEST] , with the header X-Postwind-Test: 1. An address in the project’s suppression list gets nothing (suppressed). Each address’s outcome is in results; a refusal by the recipient’s server is an outcome, not an error. Nothing is written. Needs scope send. A node that cannot send through the project’s transport answers 422 precondition_failed (transport_unavailable); available_transports of GET /api/v1/server lists the ones it can.

Parameters

NameInTypeDescription
project_idrequired path string · uuid The project’s id
template_idrequired path string · uuid The message template’s id
Idempotency-Key header string

1–128 characters · pattern ^[!-~]{1,128}$

 A key of the client’s choosing, one per request it means to send once (a UUID will do). A repeat with the same key and the same body within 24 h creates nothing again and gets the first answer, marked Idempotent-Replayed: true. The key belongs to the API key that sent it. Only a 2xx answer is kept: after any other answer the key is free again.

Request body

application/json · required

  • TestSendRequest object
  • toarray of stringrequired

    1 to 10 addresses; a repeated address (after normalization) gets one message.

    example ["me@example.com"]

  • sample_attributesobject | null

    Attributes to render with, as a subscriber’s: string, number or boolean values, up to 64 keys, up to 4 KB of JSON; any other attribute the template names is undefined. null or left out: every attribute is the text sample.

Responses

200

The outcome for each address

HeaderTypeDescription
Idempotent-Replayedstring · enumtrue when the answer is a replay of an earlier request with the same Idempotency-Key; absent otherwise.
  • TestSend object · all fields required
  • from_emailstring

    The sender: the project’s settings.from_email.

    example news@example.com

  • resultsarray of TestSendResult

    One per distinct address, in the order of the request.

    6 fields
    • TestSendResult object · all fields required
    • emailstring

      The address, normalized.

      example me@example.com

    • message_idstring | null

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

    • outcomeTestSendOutcome

      How the test message to one address went.

      • accepted
      • deferred
      • rejected
      • suppressed
      • failed
    • smtp_codeinteger · int32 | null

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

      ≥ 0 · example 550

    • smtp_textstring | null

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

    • stageRejectStage | null

      The stage of a rejected; otherwise null.

      • connect
      • rcpt
      • data
  • subjectstring

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

    example [TEST] Welcome, Ann

  • transportstring

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

    example direct

400

Not JSON (invalid_json)

Problem (application/problem+json)

401

No valid key

Problem (application/problem+json)

403

A project key without scope send (forbidden)

Problem (application/problem+json)

404

No such project or template in it, or another project’s (not_found)

Problem (application/problem+json)

409

The project is deleted (conflict); or a request with the same Idempotency-Key has not answered yet (idempotency_key_in_progress)

Problem (application/problem+json)

413

Over 10 MB (body_too_large)

Problem (application/problem+json)

415

Not application/json (unsupported_media_type)

Problem (application/problem+json)

422

Invalid fields, every one in errors (validation_failed): no address or more than 10 in to, an invalid address (to.<index>), invalid attributes, a partial (template_id), or the template does not render with this data; or unmet preconditions (precondition_failed): no settings.from_email, a transport the node cannot send through (transport / transport_unavailable); or the Idempotency-Key was used in the last 24 h for another request (idempotency_key_reused), or is not 1 to 128 visible ASCII characters (validation_failed, field Idempotency-Key)

Problem (application/problem+json)

429

The key is over its rate limit, api.rate_limit_per_minute requests a minute on this node (rate_limited)

HeaderTypeDescription
Retry-AfterintegerSeconds until the key’s next request passes; rounded up.

Problem (application/problem+json)

504

Postwind’s storage did not answer within its time limit (storage_timeout). A change the request makes may still take effect: check before repeating it. A repeat with the same Idempotency-Key never runs it twice: it is 409 idempotency_key_in_progress until the key’s 24 h end

Problem (application/problem+json)