Skip to content

Konigle Python SDK

Email Identities

konigle/konigle-python

Email Identities¶

The Konigle SDK provides comprehensive email identity management for verifying domains and email addresses used for sending emails. Email identities must be verified before they can be used to send emails, including DKIM and SPF configuration for proper email authentication.

Understanding Email Identities¶

Email identities are domains or email addresses that have been verified for sending emails:

Domain Identity: Verifies an entire domain (e.g., example.com)
Email Identity: Verifies a specific email address (e.g., noreply@example.com)
DKIM Verification: Ensures email authenticity through cryptographic signatures
SPF/MAIL FROM: Custom envelope sender configuration for better deliverability

Creating Email Identities¶

Domain Identity Creation¶

import konigle
from konigle.models.comm import EmailIdentityCreate

client = konigle.Client(api_key="your-api-key")

# Create a domain identity
identity_data = EmailIdentityCreate(
    identity_value="example.com"
)

identity = client.email_identities.create(identity_data)
print(f"Created identity: {identity.id}")
print(f"Identity type: {identity.identity_type}")  # "domain"
print(f"Identity value: {identity.identity_value}")  # "example.com"
print(f"Verified: {identity.verified}")  # False (initially)
print(f"DKIM verified: {identity.dkim_verified}")

# Check if DNS records are provided for verification
if identity.dkim_records:
    print("\n🔧 DKIM Records Required:")
    for i, record in enumerate(identity.dkim_records, 1):
        print(f"Record {i}:")
        print(f"  Type: {record['type']}")
        print(f"  Name: {record['name']}")
        print(f"  Value: {record['value']}")
        if record.get('description'):
            print(f"  Purpose: {record['description']}")

Email Address Identity Creation¶

# Create an email address identity
email_identity_data = EmailIdentityCreate(
    identity_value="noreply@example.com"
)

email_identity = client.email_identities.create(email_identity_data)
print(f"Created email identity: {email_identity.identity_value}")
print(f"Identity type: {email_identity.identity_type}")  # "email"
print(f"Verified: {email_identity.verified}")

You will receive a verification email at the specified address. Click the link in the email to complete verification. Once verified you can use check status method to get the status of verification.

Listing Email Identities¶

Basic Identity Listing¶

# List all identities with pagination
identities = client.email_identities.list(page=1, page_size=20)

print(f"Total identities: {identities.count}")
print(f"Current page: {identities.current_page}")
print(f"Total pages: {identities.num_pages}")

for identity in identities.payload:
    print(f"- {identity.identity_value} ({identity.identity_type})")
    print(f"  Verified: {identity.verified}")
    print(f"  DKIM: {identity.dkim_verified}")
    if identity.mail_from_domain:
        print(f"  MAIL FROM: {identity.mail_from_domain}")
    print(f"  Created: {identity.created_at}")

Filtering Identities¶

from konigle.filters.comm import EmailIdentityFilters

# Using filter object (type-safe)
identity_filters = EmailIdentityFilters(
    q="example.com",  # Search in identity value
    identity_type="domain",  # Filter by type
)

filtered_identities = client.email_identities.list(
    page=1,
    page_size=10,
    filters=identity_filters
)

# Using filter kwargs (more concise)
domain_identities = client.email_identities.list(
    identity_type="domain"
)

email_identities = client.email_identities.list(
    identity_type="email"
)

# Search identities by value
search_results = client.email_identities.list(q="company")

print(f"Domain identities: {len(domain_identities.payload)}")
print(f"Email identities: {len(email_identities.payload)}")

Getting a Specific Identity¶

# Get identity by ID
identity = client.email_identities.get("identity_123456789")
print(f"Identity: {identity.identity_value}")
print(f"Type: {identity.identity_type}")
print(f"Account: {identity.account}")
print(f"Verified: {identity.verified}")
print(f"DKIM Verified: {identity.dkim_verified}")
print(f"DKIM Status: {identity.dkim_verification_status}")

# Check MAIL FROM configuration
if identity.mail_from_domain:
    print(f"MAIL FROM Domain: {identity.mail_from_domain}")
    print(f"MAIL FROM Verified: {identity.mail_from_verified}")
    print(f"MAIL FROM Status: {identity.mail_from_verification_status}")
    print(f"Use Custom MAIL FROM: {identity.use_custom_mail_from}")

# Display DNS records
if identity.dkim_records:
    print("\n🔧 DKIM DNS Records:")
    for i, record in enumerate(identity.dkim_records, 1):
        print(f"  {i}. {record['type']} {record['name']} = {record['value']}")

if identity.mail_from_records:
    print("\n🔧 MAIL FROM DNS Records:")
    for i, record in enumerate(identity.mail_from_records, 1):
        print(f"  {i}. {record['type']} {record['name']} = {record['value']}")

Identity Verification¶

Checking Verification Status¶

# Check current verification status
identity = client.email_identities.check_verification_status("identity_123456789")
print(f"Identity: {identity.identity_value}")
print(f"Overall verified: {identity.verified}")
print(f"DKIM verified: {identity.dkim_verified}")
print(f"DKIM status: {identity.dkim_verification_status}")

if identity.mail_from_domain:
    print(f"MAIL FROM verified: {identity.mail_from_verified}")
    print(f"MAIL FROM status: {identity.mail_from_verification_status}")

# The check also refreshes verification status from the email service

Monitoring Verification Progress¶

import time

def monitor_verification(identity_id: str, max_attempts: int = 10):
    """Monitor identity verification progress."""

    for attempt in range(max_attempts):
        identity = client.email_identities.check_verification_status(identity_id)

        print(f"Attempt {attempt + 1}: {identity.identity_value}")
        print(f"  DKIM: {identity.dkim_verification_status}")

        if identity.mail_from_domain:
            print(f"  MAIL FROM: {identity.mail_from_verification_status}")

        if identity.verified:
            print("✅ Identity fully verified!")
            return identity

        if attempt < max_attempts - 1:
            print("⏳ Waiting 30 seconds before next check...")
            time.sleep(30)

    print("⚠️ Verification not completed within maximum attempts")
    return identity

# Monitor verification for a specific identity
verified_identity = monitor_verification("identity_123456789")

Custom MAIL FROM Setup¶

Setting Up Custom MAIL FROM Domain¶

# Setup custom MAIL FROM domain for better deliverability
identity_id = "identity_123456789"
mail_from_domain = "mail.example.com"

identity = client.email_identities.setup_custom_mail_from(
    identity_id,
    mail_from_domain
)

print(f"✓ Custom MAIL FROM setup for: {identity.identity_value}")
print(f"MAIL FROM Domain: {identity.mail_from_domain}")
print(f"MAIL FROM Status: {identity.mail_from_verification_status}")

# Display required DNS records
if identity.mail_from_records:
    print("\n🔧 MAIL FROM DNS Records Required:")
    print("Add these records to your MAIL FROM domain DNS:")
    for i, record in enumerate(identity.mail_from_records, 1):
        print(f"Record {i}:")
        print(f"  Type: {record['type']}")
        print(f"  Name: {record['name']}")
        print(f"  Value: {record['value']}")
        if record.get('priority'):
            print(f"  Priority: {record['priority']}")
        if record.get('description'):
            print(f"  Purpose: {record['description']}")

Updating Email Identities¶

from konigle.models.comm import EmailIdentityUpdate

# Toggle custom MAIL FROM usage
update_data = EmailIdentityUpdate(
    use_custom_mail_from=True
)

updated_identity = client.email_identities.update("identity_123456789", update_data)
print(f"Custom MAIL FROM enabled: {updated_identity.use_custom_mail_from}")

# Disable custom MAIL FROM
disable_mail_from = EmailIdentityUpdate(
    use_custom_mail_from=False
)

updated_identity = client.email_identities.update("identity_123456789", disable_mail_from)
print(f"Custom MAIL FROM disabled: {updated_identity.use_custom_mail_from}")

Deleting Email Identities¶

# Delete an email identity
success = client.email_identities.delete("identity_123456789")
if success:
    print("Identity deleted successfully")
else:
    print("Failed to delete identity")

Async Operations¶

import asyncio
import konigle

async def manage_email_identities():
    async with konigle.AsyncClient(api_key="your-api-key") as client:
        # Create identity
        identity_data = EmailIdentityCreate(
            identity_value="async-example.com"
        )
        identity = await client.email_identities.create(identity_data)

        # Check verification status
        verified_identity = await client.email_identities.check_verification_status(
            identity.id
        )

        # Setup custom MAIL FROM
        mail_from_identity = await client.email_identities.setup_custom_mail_from(
            identity.id,
            "mail.async-example.com"
        )

        # Update identity
        update_data = EmailIdentityUpdate(use_custom_mail_from=True)
        updated_identity = await client.email_identities.update(
            identity.id,
            update_data
        )

        # Delete identity
        await client.email_identities.delete(identity.id)

asyncio.run(manage_email_identities())

CLI Commands¶

The Konigle CLI provides comprehensive email identity management commands.

Identity Creation¶

# Create a domain identity
konigle comm email identities create --value "example.com"

# Create an email address identity
konigle comm email identities create --value "noreply@example.com"

Identity Listing¶

# List all identities
konigle comm email identities list

# List with pagination
konigle comm email identities list --page 2 --page-size 5

# List with search
konigle comm email identities list --search "example"

# List by identity type
konigle comm email identities list --type domain
konigle comm email identities list --type email

Identity Details¶

# Get specific identity details
konigle comm email identities get identity_123456789

Identity Verification¶

# Check verification status
konigle comm email identities check-status identity_123456789

Custom MAIL FROM Setup¶

# Setup custom MAIL FROM domain
konigle comm email identities setup-mail-from identity_123456789 mail.example.com

Identity Updates¶

# Enable custom MAIL FROM usage
konigle comm email identities update identity_123456789 --use-custom-mail-from

# Disable custom MAIL FROM usage
konigle comm email identities update identity_123456789 --no-custom-mail-from

Identity Deletion¶

# Delete identity with confirmation
konigle comm email identities delete identity_123456789

# Delete identity without confirmation
konigle comm email identities delete identity_123456789 --yes