Utilities¶

2 endpoints for email-adjacent utilities — avatar lookup and mailto URI handling.

Python SDK Examples¶

Look up a Gravatar¶

gravatar hashes the email address per the Gravatar spec (lowercase, trim, MD5) and returns the avatar URL, profile URL, and raw hash. The avatar URL uses identicon as the fallback for addresses without a custom avatar.

from toolkitapi import Email

with Email(api_key="tk_...") as email:
    result = email.gravatar("[email protected]", size=80)

    print(result["email_hash"])   # "b58996c504c5638798eb6b511e6f49af"
    print(result["avatar_url"])   # "https://www.gravatar.com/avatar/b58996...?s=80&d=identicon"
    print(result["profile_url"])  # "https://www.gravatar.com/b58996..."

Display avatars in a user list¶

from toolkitapi import Email

users = [
    {"name": "Alice",   "email": "[email protected]"},
    {"name": "Bob",     "email": "[email protected]"},
    {"name": "Charlie", "email": "[email protected]"},
]

with Email(api_key="tk_...") as email:
    for user in users:
        result = email.gravatar(user["email"], size=40)
        user["avatar_url"] = result["avatar_url"]
        user["gravatar_hash"] = result["email_hash"]

# Render in a template:
for user in users:
    print(f'<img src="{user["avatar_url"]}" alt="{user["name"]}">')

Use different avatar sizes¶

Gravatar supports sizes from 1 to 2048 pixels. Request the size appropriate for your context:

from toolkitapi import Email

email_address = "[email protected]"

with Email(api_key="tk_...") as email:
    thumbnail = email.gravatar(email_address, size=32)   # Icon/favicon size
    standard  = email.gravatar(email_address, size=200)  # Profile card
    hd        = email.gravatar(email_address, size=512)  # Hero image

print("Thumbnail:", thumbnail["avatar_url"])
print("Standard:",  standard["avatar_url"])
print("HD:",        hd["avatar_url"])

Build a mailto: URI¶

mailto_build constructs a properly-encoded RFC 6068 mailto: URI from individual fields. Handles encoding of special characters in subjects and bodies.

from toolkitapi import Email

with Email(api_key="tk_...") as email:
    result = email.mailto_build(
        to=["[email protected]"],
        cc=["[email protected]"],
        subject="Meeting follow-up: Q2 review",
        body="Hi Alice,\n\nHere are the action items from today's meeting...",
    )

print(result["uri"])
# mailto:alice%40toolkitapi.io?cc=bob%40toolkitapi.io&subject=Meeting%20follow-up%3A%20Q2%20review&body=Hi%20Alice%2C...

Build a mailto for a feedback button¶

from toolkitapi import Email

def make_feedback_link(support_email: str, page_title: str, page_url: str) -> str:
    """Generate a mailto: link pre-filled with page context for a feedback button."""
    with Email(api_key="tk_...") as email:
        result = email.mailto_build(
            to=[support_email],
            subject=f"Feedback: {page_title}",
            body=f"Page: {page_url}\n\nFeedback:\n\n",
        )
    return result["uri"]

link = make_feedback_link(
    "[email protected]",
    "Getting Started Guide",
    "https://docs.toolkitapi.io/getting-started",
)
print(f'<a href="{link}">Send feedback</a>')

Build a mailto with multiple recipients¶

from toolkitapi import Email

with Email(api_key="tk_...") as email:
    result = email.mailto_build(
        to=["[email protected]", "[email protected]"],
        bcc=["[email protected]"],
        subject="Team update",
        body="Hi team,\n\nQuick update for this week...",
    )

print(result["uri"])
print("To:", result["fields"]["to"])
print("BCC:", result["fields"]["bcc"])

Parse a mailto: URI¶

mailto_parse decodes an RFC 6068 mailto: URI back into its component fields — useful when processing mailto links from HTML or configuration files.

from toolkitapi import Email

uris = [
    "mailto:[email protected]",
    "mailto:[email protected]?subject=Help%20needed&body=Hello%20there",
    "mailto:[email protected],[email protected][email protected]&[email protected]&subject=Meeting",
]

with Email(api_key="tk_...") as email:
    for uri in uris:
        result = email.mailto_parse(uri)
        print(f"URI:     {uri[:60]}")
        print(f"  To:      {result['fields']['to']}")
        print(f"  CC:      {result['fields']['cc']}")
        print(f"  Subject: {result['fields']['subject']}")
        print(f"  Body:    {result['fields']['body']}")
        print()

Round-trip: build then parse¶

from toolkitapi import Email

with Email(api_key="tk_...") as email:
    built = email.mailto_build(
        to=["[email protected]"],
        subject="Hello & welcome!",
        body="Thanks for signing up.\n\nBest regards",
    )
    print("Built:", built["uri"])

    # Round-trip: parse the built URI back to fields
    parsed = email.mailto_parse(built["uri"])
    assert parsed["fields"]["to"] == ["[email protected]"]
    assert parsed["fields"]["subject"] == "Hello & welcome!"
    print("Parsed subject:", parsed["fields"]["subject"])

Response Fields¶

gravatar response:

mailto response (both build and parse):