Organization → Email Settings

Owner-only. Configure how outbound signing/notification emails are sent for your organization — using the platform's shared email service, or your own SMTP/SendGrid/SES/Microsoft 365 credentials. Only visible to owners, and only when your plan allows custom email routing.

Endpoint summary

Method	Path	Notes
GET	/organization/v1/email-settings	View current configuration
PUT	/organization/v1/email-settings	Update configuration
POST	/organization/v1/email-settings/test	Send a live test email

Viewing

GET /organization/v1/email-settings

{
  "licenseSmtpEnabled": true,
  "planAllowCustomSmtp": true,
  "isOwner": true,
  "emailMode": "ORG_MANAGED",
  "source": "CUSTOM",
  "provider": "SENDGRID",
  "configurations": { "EMAIL_FROM": "no-reply@acme.example.com" },
  "allowedConnectors": [ { "id": 4, "name": "Shared SendGrid", "provider": "SENDGRID" } ]
}

Updating

PUT /organization/v1/email-settings
Content-Type: application/json

{
  "emailMode": "ORG_MANAGED",
  "source": "CUSTOM",
  "provider": "SENDGRID",
  "configurations": { "API_KEY": "SG.xxxx", "EMAIL_FROM": "no-reply@acme.example.com" }
}

Field	Meaning
emailMode	GLOBAL (use platform default) or ORG_MANAGED (org supplies its own)
source	PLAN_CONNECTOR (pick one your plan already allows) or CUSTOM (your own credentials)
provider	SMTP, SENDGRID, AMAZON_SES, or MICROSOFT_OAUTH2
configurations	provider-specific key-value map — required keys differ per provider (see below)

Required configurations keys per provider

Provider	Keys
SMTP	SMTP_SERVER, SMTP_PORT, SSL_TLS, AUTHENTICATION, USER_ID, PASSWORD, EMAIL_FROM
SENDGRID	API_KEY, EMAIL_FROM
AMAZON_SES	API_KEY, ACCESS_KEY, REGION, EMAIL_FROM
MICROSOFT_OAUTH2	TENANT_ID, CLIENT_ID, CLIENT_SECRET, OAUTH_SCOPE, EMAIL_FROM

Secrets are masked on read

PASSWORD, CLIENT_SECRET, API_KEY, and SECRET_KEY come back masked (********) from GET. They never round-trip — resend the real value when updating, or the masked placeholder will be saved as the credential.

Testing

POST /organization/v1/email-settings/test
Content-Type: application/json

{ "connectorId": 4, "provider": "SENDGRID", "configurations": { "API_KEY": "SG.xxxx" }, "testRecipient": "jane@example.com" }

{ "success": true, "provider": "SENDGRID", "step": "SEND", "message": "Test email sent" }

step on failure indicates where it broke: CONFIG, CONNECT, AUTH, TOKEN, or SEND — use this to tell a user "your API key is wrong" vs. "we couldn't reach SendGrid" vs. "the email itself failed to send."