REST API endpoints for configuring SMTP, managing email templates, and previewing transactional emails.

Email API

HelloJohn sends transactional emails for sign-up verification, magic links, invitations, and password resets. You can configure a custom SMTP provider and customize email templates per tenant.

Email Configuration Object

{
  "provider": "smtp",
  "from_name": "Acme Auth",
  "from_email": "auth@acme.com",
  "reply_to": "support@acme.com",
  "smtp": {
    "host": "smtp.sendgrid.net",
    "port": 587,
    "username": "apikey",
    "tls": true
  },
  "updated_at": "2024-01-15T10:00:00Z"
}

GET /v1/email/config

Get the current email configuration for the tenant.

curl "https://api.hellojohn.dev/v1/email/config" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

Response: Returns the email configuration object (SMTP password is not returned).

PUT /v1/email/config

Set or update the email provider configuration.

Body:

Field	Type	Required	Description
`provider`	string	✅	`smtp` or `hellojohn` (HelloJohn's default provider)
`from_name`	string	✅	Sender display name
`from_email`	string	✅	Sender email address
`reply_to`	string	—	Reply-to address
`smtp`	object	—	Required when `provider` is `smtp`

SMTP object:

Field	Type	Required	Description
`host`	string	✅	SMTP host
`port`	integer	✅	SMTP port (typically `587` or `465`)
`username`	string	✅	SMTP username
`password`	string	✅	SMTP password or API key
`tls`	boolean	—	Use STARTTLS (default: `true`)
`ssl`	boolean	—	Use SSL (for port 465)

curl -X PUT "https://api.hellojohn.dev/v1/email/config" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "smtp",
    "from_name": "Acme Auth",
    "from_email": "auth@acme.com",
    "smtp": {
      "host": "smtp.sendgrid.net",
      "port": 587,
      "username": "apikey",
      "password": "SG.xxxxxxxxxxxx",
      "tls": true
    }
  }'

Response: 200 OK — Returns updated config (without password).

POST /v1/email/config/test

Send a test email to verify the SMTP configuration works.

Body:

Field	Type	Required	Description
`to`	string	✅	Email address to send the test to

curl -X POST "https://api.hellojohn.dev/v1/email/config/test" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{"to": "you@example.com"}'

Response: 200 OK

{
  "sent": true,
  "message_id": "msg_01HABCDEF...",
  "duration_ms": 312
}

Email Templates

HelloJohn sends these built-in transactional emails:

Template	Trigger	Subject
`verification`	After sign-up	Verify your email
`magic_link`	Magic link sign-in	Sign in to `{{app_name}}`
`invitation`	Organization invitation	You've been invited
`password_reset`	Password reset request	Reset your password
`mfa_otp`	SMS/email OTP	Your verification code
`welcome`	First sign-in	Welcome to `{{app_name}}`

GET /v1/email/templates

List all email templates.

curl "https://api.hellojohn.dev/v1/email/templates" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

GET /v1/email/templates/:template

Get a specific template's content.

curl "https://api.hellojohn.dev/v1/email/templates/verification" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

Response:

{
  "id": "verification",
  "subject": "Verify your email address",
  "body_html": "<html>...</html>",
  "body_text": "Please verify your email...",
  "variables": ["verify_url", "user_email", "app_name", "expires_in"],
  "customized": false
}

PUT /v1/email/templates/:template

Override a template with custom content. Use Handlebars-style {{variable}} placeholders.

Body:

Field	Type	Description
`subject`	string	Email subject line
`body_html`	string	HTML body (supports `{{variable}}`)
`body_text`	string	Plain text fallback

curl -X PUT "https://api.hellojohn.dev/v1/email/templates/welcome" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Welcome to Acme, {{user_name}}!",
    "body_html": "<p>Hi {{user_name}}, welcome aboard!</p>",
    "body_text": "Hi {{user_name}}, welcome aboard!"
  }'

DELETE /v1/email/templates/:template

Reset a template to the HelloJohn default.

Response: 204 No Content

POST /v1/email/templates/:template/preview

Preview a rendered template with sample data.

Body:

Field	Type	Description
`variables`	object	Override template variables for preview

curl -X POST "https://api.hellojohn.dev/v1/email/templates/welcome/preview" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"user_name": "Alice"}}'

Response:

{
  "subject": "Welcome to Acme, Alice!",
  "body_html": "<p>Hi Alice, welcome aboard!</p>",
  "body_text": "Hi Alice, welcome aboard!"
}

Email API

On this page