/v1/workspaces/{workspace_id}/smtp-configAuthCreate or update the workspace-default SMTP config (resets verification)
Path parameters
workspace_id*string · uuidId of the workspace.
Headers
Idempotency-KeystringOpaque 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*stringSMTP server hostname.
Example: "smtp.sendgrid.net"
port*numberSMTP server port (commonly 587 for STARTTLS, 465 for implicit TLS).
Example: 587
secure*booleanWhether to use implicit TLS (true → port 465 style). For STARTTLS on 587, set false.
Example: false
usernamestringSMTP username. May be omitted alongside password for anonymous SMTP (e.g. postfix on a private network); otherwise both are required.
passwordstringSMTP password. Stored encrypted at rest; never returned by GET endpoints.
from_name*stringDefault From name on outbound messages.
Example: "Acme Notifications"
from_email*string · emailDefault From email address. Must be authorized to send on the chosen domain.
Example: "noreply@acme.com"
Response · 200
workspace_id*string · uuidThe workspace the configuration belongs to.
domain_id*string · uuidNull for the workspace-default config, set for a per-domain override.
host*stringSMTP server host name.
port*numberSMTP server port.
secure*booleanTrue for implicit TLS (usually port 465); false for STARTTLS or plain.
username*stringSMTP user name; null when the server needs no authentication.
password*stringAlways null on the wire — the stored ciphertext is never returned.
password_set*booleanTrue when a password is stored (it is never returned).
from_name*stringSender display name used for mail sent through this server.
from_email*string · emailSender 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-timeWhen the connection last verified; null if never.
last_verify_error*stringWhy the last verification failed; null when it passed.
created_at*string · date-timeWhen the configuration was created.
updated_at*string · date-timeWhen the configuration was last changed.
Example
Request
PUT https://api.mail.productcraft.co/v1/workspaces/{workspace_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"
}