> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hanko.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How to customize Hanko's emails

> Send Hanko emails with your own text and style.

<div class="hidden">
  **Hanko Custom Emails Guide**:

  **About Hanko**:

  Hanko is a modern open source authentication solution and the fastest way you integrate passkeys, 2FA, SSO, and more—with full control over your data. Move between self-hosted and Hanko Cloud anytime. No lock-in. Just Auth how it should be: secure, user friendly, and fully yours.

  **What This Guide Covers**: This guide demonstrates how to implement custom email delivery for Hanko authentication flows. You'll learn to disable Hanko's default email service and handle authentication emails through your own email infrastructure and templates.

  **Key Technologies**:

  * Webhooks (email.send events)
  * Email Service Providers
  * HTML Email Templates
  * JWT Token Processing
  * Hanko Cloud Console

  **Prerequisites**:

  * Hanko Pro or Enterprise plan subscription
  * Email service provider account
  * Webhook endpoint development capability
  * Basic understanding of email delivery systems
  * JWT token processing knowledge

  **Tasks You'll Complete**:

  * Create webhook for email.send events
  * Disable Hanko's default email delivery
  * Process webhook payloads for email data
  * Design custom email templates
  * Implement email sending logic
  * Test custom email delivery flows
</div>

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.

<Note>
  New to webhooks? Check out our comprehensive [Webhooks guide](/guides/webhooks) first.
</Note>

## Disable email delivery by Hanko

<Note>
  This feature is only available in the Pro or Enterprise [plans](https://www.hanko.io/pricing).
</Note>

<Steps>
  <Step title={"Access email delivery settings"}>
    Log in to Hanko Cloud, select your organization and project, then navigate to `Settings > Email delivery`.
  </Step>

  <Step title={"Disable default email delivery"}>
    Set the `Email delivery` setting to `Off` to disable default email sending.
  </Step>
</Steps>

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:

<AccordionGroup>
  <Accordion title={"'email.send' token payload example"} defaultOpen={true}>
    ```json theme={null}
    {
        "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"
    }
    ```
  </Accordion>

  <Accordion title={"'email.send' token payload properties"}>
    <ResponseField name="aud" type="string[]">
      The recipients the token is intended for
    </ResponseField>

    <ResponseField name="data" type="object">
      <Expandable>
        <ResponseField name="subject" type="string">
          The subject line of the email
        </ResponseField>

        <ResponseField name="body_plain" type="string">
          The plain text version of the email body
        </ResponseField>

        <ResponseField name="body" type="string">
          The HTML version of the email body (nullable)
        </ResponseField>

        <ResponseField name="to_email_address" type="string">
          The recipient’s email address
        </ResponseField>

        <ResponseField name="delivered_by_hanko" type="boolean">
          Indicates whether the email was delivered by Hanko (`true`) or not (`false`).
        </ResponseField>

        <ResponseField name="accept_laguage" type="boolean">
          Deprecated, rely on `language` instead.

          The preferred language for the email content.
        </ResponseField>

        <ResponseField name="language" type="string">
          The preferred language for the email content.
        </ResponseField>

        <ResponseField name="type" type="enum<string>">
          The type of the email being sent or to be sent.

          Available options: `login`, `email_login_attempted`, `email_registration_attempted`, `email_verification`,
          `recovery`, `security_notification`
        </ResponseField>

        <ResponseField name="data" type="object">
          Additional data.

          <Expandable>
            <ResponseField name="service_name" type="string">
              The name of the service set in the Console as the project name
            </ResponseField>

            <ResponseField name="otp_code" type="string">
              The passcode the user can use to log in
            </ResponseField>

            <ResponseField name="ttl" type="number">
              The validity duration of the passcode in seconds
            </ResponseField>

            <ResponseField name="valid_until" type="number">
              The Unix timestamp indicating when the passcode expires
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="evt" type="string">
      The event that triggered the webhook containing this data
    </ResponseField>

    <ResponseField name="exp" type="number">
      The expiration date of the token
    </ResponseField>

    <ResponseField name="iat" type="number">
      The time at which the token was issued
    </ResponseField>

    <ResponseField name="sub" type="string" default="hanko webhooks" />
  </Accordion>
</AccordionGroup>

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.