Mail API reference

Mail API · Sending-Defaults

put/v1/workspaces/{workspace_id}/sending-defaultsAuth

Set or clear the workspace default sender

Replaces the default sender (`address: null` clears it). The change applies to the next send of every product at once, and emits a `sending_defaults.updated` webhook event. Repeating the same request changes nothing, so it takes no `Idempotency-Key`.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Request body

address*string

The new default From, or null to clear it. A bare address or `Name <address>` (display name up to 200 characters). Its domain must be a sending domain of this workspace (it may still be pending verification; `verified` in the response says whether it sends yet).

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

Response · 200

default_sender*object

The workspace default sender, or null when none is set. With none set, a template send with no `from` is skipped: the HTTP route answers 422 `no_default_sender`, and an `email.skipped` webhook event is logged.

skipped_sends*object

Sends skipped for want of a sender (`no_default_sender`). A non-zero `count` means some product emails did not go out: set a default sender.

updated_at*string · date-time

When the settings last changed (set, cleared, or first created by a skipped send); null when there are none.

Example: "2026-10-17T09:30:00.000Z"

Example

Request

PUT https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/sending-defaults
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "address": "Acme <hello@acme.com>"
}

Response

{
  "default_sender": {},
  "skipped_sends": {},
  "updated_at": "2026-10-17T09:30:00.000Z"
}