Send Custom Emails - Hanko

On this page

Create a Webhook
Disable Hanko’s Email Delivery
Send Custom Emails

This guide walks you through implementing custom email delivery instead of using Hanko’s default email service.

Create a Webhook

Set up a webhook subscription for the email.send event. This webhook triggers whenever Hanko needs to send an authentication email.

New to webhooks? Check out our comprehensive Webhooks guide first.

Disable Hanko’s Email Delivery

This feature is only available in the Pro or Enterprise plan.

1

Access email delivery settings

Log in to Hanko Cloud, select your organization and project, then navigate to Settings > Email delivery.

2

Disable default email delivery

Locate the Email delivery by Hanko setting and toggle it off to disable default email sending.

Once disabled, Hanko will no longer send emails automatically. All email delivery becomes your responsibility through webhook handling.

Send Custom Emails

When Hanko needs to send an email, the email.send webhook event triggers with all necessary data for custom email delivery. The webhook token payload contains comprehensive email information:

'email.send' token payload example

{
    "aud": [
        "Test Service ABC"
    ],
    "data": {
        "subject": "Use passcode 325139 to verify your email address",
        "body_plain": "Enter the following passcode to verify your email address:\n\n325139\n\nThe passcode is valid for 5 minutes.",
        "to_email_address": "test@example.com",
        "delivered_by_hanko": false,
        "language": "en",
        "type": "passcode",
        "data": {
            "service_name": "Test Service ABC",
            "otp_code": "325139",
            "ttl": 300,
            "valid_until": 1737128997
        }
    },
    "evt": "email.send",
    "exp": 1737128997,
    "iat": 1737128697,
    "sub": "hanko webhooks"
}

'email.send' token payload properties

The data property contains type-specific information for email personalization. This structure varies based on the email type being sent (verification, password reset, etc.). Use the webhook data to compose and deliver emails through your preferred email service provider or custom infrastructure, giving you complete control over email design and delivery.

Webhooks Custom domain