engagelab-email

Official EngageLab Email Python SDK.

Python SDK for EngageLab Email sending APIs.

Supported sending APIs:

• Normal email: POST /v1/mail/send
• Template email: POST /v1/mail/sendtemplate
• Calendar email: POST /v1/mail/sendcalendar
• MIME email: POST /v1/mail/send_mime

Default base URLs:

• Singapore: https://email.api.engagelab.cc
• Turkey: https://emailapi-tr.engagelab.com

Install

pip install engagelab-email

Local Development

python -m pip install -e .
python -m unittest discover -s tests

Normal Email

from engagelab_email import EngageLabEmailClient

client = EngageLabEmailClient(
    api_user="your_api_user",
    api_key="your_api_key",
)

result = client.send({
    "from": "EngageLab Team <support@mail.engagelab.com>",
    "to": ["user@example.com"],
    "body": {
        "subject": "Welcome",
        "content": {
            "html": "<p>Hello from EngageLab</p>",
            "text": "Hello from EngageLab",
        },
    },
})

print(result)

Template Email

client.send_template({
    "from": "support@mail.engagelab.com",
    "to": ["user@example.com"],
    "body": {
        "template_invoke_name": "month_bill",
        "subject": "Monthly Bill",
        "vars": {
            "%name%": ["Jack"],
            "%money%": ["30"],
        },
    },
})

Calendar Email

client.send_calendar({
    "from": "EngageLab Team <support@mail.engagelab.com>",
    "to": ["user@example.com"],
    "body": {
        "subject": "Meeting",
        "content": {
            "html": "<p>Please join the meeting.</p>",
        },
        "calendar": {
            "time_zone_id": "Asia/Shanghai",
            "start_time": "2026-06-10 10:00:00",
            "end_time": "2026-06-10 11:00:00",
            "title": "Project Meeting",
            "organizer": {
                "name": "EngageLab",
                "email": "support@mail.engagelab.com",
            },
            "location": "Online",
        },
    },
})

MIME Email

client.send_mime({
    "from": "EngageLab Team <support@mail.engagelab.com>",
    "to": ["user@example.com"],
    "body": {
        "subject": "Raw MIME",
        "content": {
            "raw_message": "From: test@example.com\r\nTo: user@example.com\r\nSubject: Raw MIME\r\n\r\nHello",
        },
    },
})

Turkey Data Center

from engagelab_email import EngageLabEmailClient, TURKEY_BASE_URL

client = EngageLabEmailClient(
    api_user="your_api_user",
    api_key="your_api_key",
    base_url=TURKEY_BASE_URL,
)

Error Handling

from engagelab_email import EngageLabEmailError

try:
    client.send({"body": {}})
except EngageLabEmailError as error:
    print(error.status, error.code, error.response)

The SDK accepts request payloads in the same shape as EngageLab's REST API.

Anonymous Usage Metrics

The SDK adds an anonymous installation ID to API request headers so EngageLab can measure distinct SDK installations. The ID is stored locally under ~/.config/engagelab-email/telemetry.json; no API keys, email content, or recipients are collected. The first successful API request also carries X-EngageLab-SDK-Init: 1.

To disable these headers:

ENGAGELAB_EMAIL_TELEMETRY_DISABLED=1 python app.py