Mail API reference

Mail API · Domains

post/v1/workspaces/{workspace_id}/domains/{domain_id}/test-sendAuth

Send a built-in test email from this domain, no template needed.

Sends a fixed message (subject `[TEST] Sending from <domain> works`, a short body naming the domain and the From address) so a freshly verified domain can be tried before any template exists. The From address defaults to `test@<domain>` and must be at this exact domain. Like a template test send it skips the suppression list and the ordinary send limits, counts against the workspace test-send limit (30 per hour), and is recorded with `source: test_send`.

Path parameters

workspace_id*string · uuid

Id of the workspace.

domain_id*string · uuid

Id of the domain.

Headers

Idempotency-Keystring

Opaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. A retry with the same key and body returns the original response with `Idempotent-Replay: true`.

Request body

fromstring

Sender. Either a bare address (`hello@acme.com`) or a display name plus the address in angle brackets (`Acme <hello@acme.com>`; quote a name that contains a comma: `"Acme, Inc." <hello@acme.com>`). The display name is at most 200 characters. The address's domain must itself be an active (verified) sending domain of the workspace; a verified subdomain does not cover its parent (with only `mail.acme.com` verified, `hello@acme.com` is refused with 422 `from_domain_not_verified`). Must be an address at this exact domain. Defaults to `test@<domain>`.

Example: "Acme <hello@acme.com>"

to*string · email

Recipient of the test email. The suppression list is not checked for test sends; they count against the workspace test-send limit (30 per hour) instead of the send limits.

Example: "you@acme.com"

Response · 202 Accepted; queued for delivery.

id*string · uuid

Id of the stored message (`outbound_message.id`). Pass it to `GET /messages/{id}` and match it against `data.email_id` on webhook events. Null only if the message log write failed; the send itself was still queued.

Example: "4f8b2c1e-9a3d-4e57-b6f0-2d1c8e7a9b05"

accepted*boolean

Always true on a 202.

Example: true

from*string

The From field as sent, display name included.

Example: "Acme <hello@acme.com>"

to*object

The `to` field as sent: one address, or the array.

Example: "user@example.com"

subject*string

The rendered subject line.

email_id*string · uuid

The email this send created (`GET /emails/{id}`): one email, one message per recipient. Equals `id` for a send whose first message was recorded.

Example: "4f8b2c1e-9a3d-4e57-b6f0-2d1c8e7a9b05"

Example

Request

POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/domains/{domain_id}/test-send
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "from": "Acme <hello@acme.com>",
  "to": "you@acme.com"
}

Response

{
  "id": "4f8b2c1e-9a3d-4e57-b6f0-2d1c8e7a9b05",
  "accepted": true,
  "from": "Acme <hello@acme.com>",
  "to": "user@example.com",
  "subject": "string",
  "email_id": "4f8b2c1e-9a3d-4e57-b6f0-2d1c8e7a9b05"
}