Skip to content

EmailNotifier

Send email notifications via SMTP.

Import

from xeepy.notifications import EmailNotifier

Class Signature

class EmailNotifier:
    def __init__(
        self,
        smtp_host: str,
        smtp_port: int = 587,
        username: str = None,
        password: str = None,
        from_email: str = None,
        use_tls: bool = True
    )

Parameters

Parameter Type Default Description
smtp_host str Required SMTP server hostname
smtp_port int 587 SMTP port
username str None SMTP username
password str None SMTP password/app password
from_email str None Sender email address
use_tls bool True Use TLS encryption

Methods

Method Returns Description
send(to, subject, body) bool Send email
send_html(to, subject, html) bool Send HTML email
notify_unfollowers(to, users) bool Report unfollowers
notify_report(to, report) bool Send analytics report

send

async def send(
    self,
    to: Union[str, List[str]],
    subject: str,
    body: str
) -> bool

Send a plain text email.

send_html

async def send_html(
    self,
    to: Union[str, List[str]],
    subject: str,
    html: str,
    text_fallback: str = None
) -> bool

Send an HTML email with optional text fallback.

Common SMTP Settings

Provider Host Port Notes
Gmail smtp.gmail.com 587 Requires App Password
Outlook smtp.office365.com 587
Yahoo smtp.mail.yahoo.com 587 Requires App Password
SendGrid smtp.sendgrid.net 587 Use API key as password

Usage Examples

Basic Setup

from xeepy.notifications import EmailNotifier

# Gmail setup (requires App Password)
notifier = EmailNotifier(
    smtp_host="smtp.gmail.com",
    smtp_port=587,
    username="your-email@gmail.com",
    password="your-app-password",
    from_email="your-email@gmail.com"
)

Send Simple Email

from xeepy.notifications import EmailNotifier

async def main():
    notifier = EmailNotifier(
        smtp_host="smtp.gmail.com",
        username="your-email@gmail.com",
        password="your-app-password",
        from_email="your-email@gmail.com"
    )

    await notifier.send(
        to="recipient@example.com",
        subject="Test from Xeepy",
        body="Hello! This is a test email from Xeepy."
    )

asyncio.run(main())

Send to Multiple Recipients

from xeepy.notifications import EmailNotifier

async def main():
    notifier = EmailNotifier(
        smtp_host="smtp.gmail.com",
        username="your-email@gmail.com",
        password="your-app-password",
        from_email="your-email@gmail.com"
    )

    await notifier.send(
        to=["user1@example.com", "user2@example.com"],
        subject="Weekly Report",
        body="Here's your weekly Twitter analytics report."
    )

asyncio.run(main())

Send HTML Email

from xeepy.notifications import EmailNotifier

async def main():
    notifier = EmailNotifier(
        smtp_host="smtp.gmail.com",
        username="your-email@gmail.com",
        password="your-app-password",
        from_email="your-email@gmail.com"
    )

    html = """
    <html>
    <body>
        <h1>📊 Twitter Daily Report</h1>
        <table border="1" cellpadding="10">
            <tr>
                <th>Metric</th>
                <th>Value</th>
                <th>Change</th>
            </tr>
            <tr>
                <td>Followers</td>
                <td>10,532</td>
                <td style="color: green;">+15</td>
            </tr>
            <tr>
                <td>Following</td>
                <td>892</td>
                <td>0</td>
            </tr>
        </table>
        <p><i>Generated by Xeepy</i></p>
    </body>
    </html>
    """

    await notifier.send_html(
        to="recipient@example.com",
        subject="Daily Twitter Report",
        html=html,
        text_fallback="Followers: 10,532 (+15)"
    )

asyncio.run(main())

Notify on Unfollowers

from xeepy import Xeepy
from xeepy.notifications import EmailNotifier

async def email_unfollowers():
    notifier = EmailNotifier(
        smtp_host="smtp.gmail.com",
        username="your-email@gmail.com",
        password="your-app-password",
        from_email="your-email@gmail.com"
    )

    async with Xeepy() as x:
        report = await x.monitor.unfollowers()

        if report.unfollowers:
            await notifier.notify_unfollowers(
                to="your-email@example.com",
                users=report.unfollowers
            )

asyncio.run(email_unfollowers())

Weekly Analytics Report

from xeepy import Xeepy
from xeepy.notifications import EmailNotifier

async def weekly_report():
    notifier = EmailNotifier(
        smtp_host="smtp.gmail.com",
        username="your-email@gmail.com",
        password="your-app-password",
        from_email="your-email@gmail.com"
    )

    async with Xeepy() as x:
        user = await x.scrape.profile("myaccount")
        engagement = await x.analytics.engagement("myaccount", period="7d")

        html = f"""
        <html>
        <body>
            <h1>Weekly Report: @{user.username}</h1>

            <h2>Account Stats</h2>
            <ul>
                <li>Followers: {user.followers_count:,}</li>
                <li>Following: {user.following_count:,}</li>
                <li>Tweets: {user.tweet_count:,}</li>
            </ul>

            <h2>Engagement (7 days)</h2>
            <ul>
                <li>Total likes: {engagement.total_likes:,}</li>
                <li>Total retweets: {engagement.total_retweets:,}</li>
                <li>Engagement rate: {engagement.engagement_rate:.2f}%</li>
            </ul>
        </body>
        </html>
        """

        await notifier.send_html(
            to="your-email@example.com",
            subject=f"Weekly Twitter Report - @{user.username}",
            html=html
        )

asyncio.run(weekly_report())

SendGrid Setup

from xeepy.notifications import EmailNotifier

# Using SendGrid
notifier = EmailNotifier(
    smtp_host="smtp.sendgrid.net",
    smtp_port=587,
    username="apikey",  # Always "apikey" for SendGrid
    password="SG.your-api-key-here",
    from_email="your-verified-sender@example.com"
)

Environment Variables

import os
from xeepy.notifications import EmailNotifier

notifier = EmailNotifier(
    smtp_host=os.getenv("SMTP_HOST"),
    smtp_port=int(os.getenv("SMTP_PORT", 587)),
    username=os.getenv("SMTP_USERNAME"),
    password=os.getenv("SMTP_PASSWORD"),
    from_email=os.getenv("FROM_EMAIL")
)

Scheduled Daily Email

from xeepy import Xeepy
from xeepy.notifications import EmailNotifier
import asyncio

async def daily_email_report():
    notifier = EmailNotifier(
        smtp_host="smtp.gmail.com",
        username="your-email@gmail.com",
        password="your-app-password",
        from_email="your-email@gmail.com"
    )

    while True:
        async with Xeepy() as x:
            user = await x.scrape.profile("myaccount")
            report = await x.monitor.unfollowers()

            body = f"""
Daily Twitter Report for @{user.username}

Stats:
- Followers: {user.followers_count:,}
- Following: {user.following_count:,}
- Tweets: {user.tweet_count:,}

Changes:
- New followers: +{len(report.new_followers)}
- Unfollowers: -{len(report.unfollowers)}

Generated by Xeepy
"""

            await notifier.send(
                to="your-email@example.com",
                subject=f"Daily Report: @{user.username}",
                body=body
            )

        # Wait 24 hours
        await asyncio.sleep(86400)

asyncio.run(daily_email_report())

Error Handling

from xeepy.notifications import EmailNotifier

async def safe_send():
    notifier = EmailNotifier(
        smtp_host="smtp.gmail.com",
        username="your-email@gmail.com",
        password="your-app-password",
        from_email="your-email@gmail.com"
    )

    try:
        success = await notifier.send(
            to="recipient@example.com",
            subject="Test",
            body="Test message"
        )
        if success:
            print("Email sent!")
        else:
            print("Failed to send")
    except Exception as e:
        print(f"Error: {e}")

asyncio.run(safe_send())

See Also