Mail API reference

Mail API · Smtp-Config

put/v1/workspaces/{workspace_id}/domains/{domain_id}/smtp-configAuth

Create or update the per-domain SMTP override (resets verification)

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

host*string

SMTP server hostname.

Example: "smtp.sendgrid.net"

port*number

SMTP server port (commonly 587 for STARTTLS, 465 for implicit TLS).

Example: 587

secure*boolean

Whether to use implicit TLS (true → port 465 style). For STARTTLS on 587, set false.

Example: false

usernamestring

SMTP username. May be omitted alongside password for anonymous SMTP (e.g. postfix on a private network); otherwise both are required.

passwordstring

SMTP password. Stored encrypted at rest; never returned by GET endpoints.

from_name*string

Default From name on outbound messages.

Example: "Acme Notifications"

from_email*string · email

Default From email address. Must be authorized to send on the chosen domain.

Example: "noreply@acme.com"

Response · 200

workspace_id*string · uuid

The workspace the configuration belongs to.

domain_id*string · uuid

Null for the workspace-default config, set for a per-domain override.

host*string

SMTP server host name.

port*number

SMTP server port.

secure*boolean

True for implicit TLS (usually port 465); false for STARTTLS or plain.

username*string

SMTP user name; null when the server needs no authentication.

password*string

Always null on the wire — the stored ciphertext is never returned.

password_set*boolean

True when a password is stored (it is never returned).

from_name*string

Sender display name used for mail sent through this server.

from_email*string · email

Sender address used for mail sent through this server.

status*object

`pending` until the connection is verified, then `active`; `failed` when the last check failed.

last_verified_at*string · date-time

When the connection last verified; null if never.

last_verify_error*string

Why the last verification failed; null when it passed.

created_at*string · date-time

When the configuration was created.

updated_at*string · date-time

When the configuration was last changed.

Example

Request

PUT https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/domains/{domain_id}/smtp-config
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "host": "smtp.sendgrid.net",
  "port": 587,
  "secure": false,
  "username": "string",
  "password": "string",
  "from_name": "Acme Notifications",
  "from_email": "noreply@acme.com"
}

Response

{
  "workspace_id": "00000000-0000-0000-0000-000000000000",
  "domain_id": "00000000-0000-0000-0000-000000000000",
  "host": "string",
  "port": 0,
  "secure": false,
  "username": "string",
  "password": "string",
  "password_set": false,
  "from_name": "string",
  "from_email": "user@example.com",
  "status": {},
  "last_verified_at": "2026-01-01T00:00:00.000Z",
  "last_verify_error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}