Skip to main content
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 email delivery by Hanko

This feature is only available in the Pro or Enterprise plans.
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

Set the Email delivery setting to Off to disable default email sending.
Once disabled, Hanko will no longer send emails for you. All email sending 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": "[email protected]",
        "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"
}
​
aud
string[]
The recipients the token is intended for
​
data
object
​
evt
string
The event that triggered the webhook containing this data
​
exp
number
The expiration date of the token
​
iat
number
The time at which the token was issued
​
sub
string
default:"hanko webhooks"
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.