Email Templates API

Customize the email templates sent by Ithbat IAM for password resets, welcome messages, invitations, MFA codes, and email verification. Each tenant has its own set of templates that inherit from the system defaults until overridden.

Admin endpoints require a Bearer token with the appropriate permission. All endpoints are scoped to the tenant identified by the X-Tenant-ID header.

Permission convention: resource:read grants list/get access. resource:write grants create/update access.

Base path: https://api.ithbat.io/api/v1/

Templates

GET /api/v1/email-templates

Permission: email_template:read

List all email templates for the tenant.

curl "https://api.ithbat.io/api/v1/email-templates" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>"

Response 200

{
  "success": true,
  "data": {
    "templates": [
      {
        "id": "tmpl_password_reset",
        "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
        "name": "Password Reset",
        "type": "password_reset",
        "subject": "Reset your {{tenant_name}} password",
        "htmlBody": "<!DOCTYPE html>...",
        "textBody": "Hi {{first_name}},\n\nReset your password: {{reset_link}}\n\nThis link expires in {{expiry_minutes}} minutes.",
        "locale": "en",
        "variables": ["first_name", "reset_link", "expiry_minutes", "tenant_name"],
        "updatedAt": "2026-02-10T09:00:00Z"
      },
      {
        "id": "tmpl_welcome",
        "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
        "name": "Welcome",
        "type": "welcome",
        "subject": "Welcome to {{tenant_name}}",
        "htmlBody": "<!DOCTYPE html>...",
        "textBody": "Hi {{first_name}},\n\nYour account is ready. Sign in at {{login_url}}",
        "locale": "en",
        "variables": ["first_name", "login_url", "tenant_name"],
        "updatedAt": "2026-01-15T00:00:00Z"
      }
    ],
    "total": 6
  }
}

GET /api/v1/email-templates/{id}

Permission: email_template:read

Get a single template by ID, including the full htmlBody and textBody.

curl "https://api.ithbat.io/api/v1/email-templates/tmpl_password_reset" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>"

Response 200

{
  "success": true,
  "data": {
    "id": "tmpl_password_reset",
    "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
    "name": "Password Reset",
    "type": "password_reset",
    "subject": "Reset your {{tenant_name}} password",
    "htmlBody": "<!DOCTYPE html><html><body><p>Hi {{first_name}},</p><p><a href=\"{{reset_link}}\">Reset your password</a>. This link expires in {{expiry_minutes}} minutes.</p></body></html>",
    "textBody": "Hi {{first_name}},\n\nReset your password: {{reset_link}}\n\nThis link expires in {{expiry_minutes}} minutes.",
    "locale": "en",
    "variables": ["first_name", "reset_link", "expiry_minutes", "tenant_name"],
    "updatedAt": "2026-02-10T09:00:00Z"
  }
}

Template Fields

Field	Type	Description
`id`	string	Template identifier
`tenantId`	string	Owning tenant UUID
`name`	string	Display name of the template
`type`	string	Template type — see supported types below
`subject`	string	Email subject line (supports template variables)
`htmlBody`	string	Full HTML email body (supports template variables)
`textBody`	string	Plain-text fallback body (supports template variables)
`locale`	string	BCP 47 locale tag (e.g., `en`, `ar`, `fr`)
`variables`	string[]	List of variable names available for interpolation in this template
`updatedAt`	string	ISO 8601 timestamp of the last update

Supported Template Types

Type	Trigger
`password_reset`	User requests a password reset
`welcome`	New user account is created
`user_invitation`	Admin sends an invitation
`mfa_code`	MFA one-time code is delivered by email
`email_verification`	User must verify their email address
`magic_link`	Passwordless magic link login is requested

PUT /api/v1/email-templates/{id}

Permission: email_template:write

Update a template's subject, HTML body, or text body. Variable interpolation uses {{variable_name}} syntax.

Request Body

Field	Type	Required	Description
`subject`	string	No	New subject line
`htmlBody`	string	No	New HTML email body
`textBody`	string	No	New plain-text body
`locale`	string	No	BCP 47 locale tag for this template

curl -X PUT "https://api.ithbat.io/api/v1/email-templates/tmpl_welcome" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Welcome to {{tenant_name}} — get started today",
    "htmlBody": "<!DOCTYPE html><html><body><h1>Welcome, {{first_name}}!</h1><p>Your account is ready. <a href=\"{{login_url}}\">Sign in now</a>.</p></body></html>",
    "textBody": "Welcome, {{first_name}}!\n\nYour account is ready. Sign in at: {{login_url}}"
  }'

Response 200

{
  "success": true,
  "data": {
    "id": "tmpl_welcome",
    "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
    "name": "Welcome",
    "type": "welcome",
    "subject": "Welcome to {{tenant_name}} — get started today",
    "htmlBody": "<!DOCTYPE html><html><body><h1>Welcome, {{first_name}}!</h1><p>Your account is ready. <a href=\"{{login_url}}\">Sign in now</a>.</p></body></html>",
    "textBody": "Welcome, {{first_name}}!\n\nYour account is ready. Sign in at: {{login_url}}",
    "locale": "en",
    "variables": ["first_name", "login_url", "tenant_name"],
    "updatedAt": "2026-03-19T12:00:00Z"
  }
}

POST /api/v1/email-templates/{id}/preview

Permission: email_template:write

Render the template with sample variable values and return the resulting HTML and text. No email is sent.

Request Body

Field	Type	Required	Description
`variables`	object	No	Key-value pairs to substitute during rendering. Unspecified variables are filled with placeholder text.

curl -X POST "https://api.ithbat.io/api/v1/email-templates/tmpl_welcome/preview" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "first_name": "Sara",
      "tenant_name": "Acme Corp",
      "login_url": "https://auth.acme.com/login"
    }
  }'

Response 200

{
  "success": true,
  "data": {
    "subject": "Welcome to Acme Corp — get started today",
    "htmlBody": "<!DOCTYPE html><html><body><h1>Welcome, Sara!</h1><p>Your account is ready. <a href=\"https://auth.acme.com/login\">Sign in now</a>.</p></body></html>",
    "textBody": "Welcome, Sara!\n\nYour account is ready. Sign in at: https://auth.acme.com/login"
  }
}

POST /api/v1/email-templates/{id}/test

Permission: email_template:write

Render the template and deliver it to a specified email address. Use this to verify the template renders correctly across email clients before it reaches real users.

Request Body

Field	Type	Required	Description
`to`	string	Yes	Recipient email address for the test delivery
`variables`	object	No	Key-value pairs to substitute during rendering

curl -X POST "https://api.ithbat.io/api/v1/email-templates/tmpl_password_reset/test" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "variables": {
      "first_name": "Omar",
      "tenant_name": "Acme Corp",
      "reset_link": "https://auth.acme.com/reset?token=example",
      "expiry_minutes": "30"
    }
  }'

Response 200

{
  "success": true,
  "data": {
    "delivered": true,
    "to": "[email protected]",
    "messageId": "msg_3e9a1f72b4c2d8e0"
  }
}

Templates​

GET /api/v1/email-templates​

GET /api/v1/email-templates/{id}​

PUT /api/v1/email-templates/{id}​

POST /api/v1/email-templates/{id}/preview​

POST /api/v1/email-templates/{id}/test​

Templates

GET /api/v1/email-templates

GET /api/v1/email-templates/{id}

PUT /api/v1/email-templates/{id}

POST /api/v1/email-templates/{id}/preview

POST /api/v1/email-templates/{id}/test