mailisk 0.9.0

Typed Python client for the Mailisk API

Mailisk Python Client

Typed Python client for the Mailisk REST API.

Mailisk is an email, SMS, outbound email, and TOTP testing platform. This package mirrors the Mailisk Node client API surface in a Python-friendly shape: methods use snake_case, response bodies stay as normal dictionaries, and the package ships TypedDict/Literal types plus py.typed.

Installation

pip install mailisk

Create A Client

Get your API key from Mailisk and pass it directly when creating a client:

from mailisk import MailiskClient

mailisk = MailiskClient(api_key="YOUR_API_KEY")

The library does not read .env files or environment variables by itself. Applications should load configuration however they prefer, then pass values to the client:

from mailisk import MailiskClient

api_key = load_api_key_from_your_config()
mailisk = MailiskClient(api_key=api_key)

Quick Start

from mailisk import MailiskClient

mailisk = MailiskClient(api_key="YOUR_API_KEY")

result = mailisk.search_inbox("mynamespace")
print(result["data"])

The client exposes Python method names such as search_inbox and list_namespaces. CamelCase aliases such as searchInbox and listNamespaces are also available for developers porting from the Node client.

Defaults

search_inbox and search_sms_messages match the Node client defaults:

• wait for at least one matching message unless wait is False
• ignore messages older than 15 minutes unless a lower bound is provided
• use a 5 minute timeout while waiting
• allow a high redirect count for wait endpoints

Timeouts are in seconds because the client uses requests:

mailisk.search_inbox(
    "mynamespace",
    {"to_addr_prefix": "[e-mail]"},
    {"timeout": 60},
)

Email

Search inbox:

response = mailisk.search_inbox(
    "mynamespace",
    {
        "to_addr_prefix": "[e-mail]",
        "subject_includes": "password",
    },
)

emails = response["data"]

List namespaces:

namespaces = mailisk.list_namespaces()
print([item["namespace"] for item in namespaces["data"]])

Download an attachment:

attachment_id = emails[0]["attachments"][0]["id"]
content = mailisk.download_attachment(attachment_id)

Outbound Email

Send an outbound email:

email = mailisk.send_email(
    "mynamespace",
    {
        "from": {"email": "[e-mail]", "name": "Support"},
        "to": ["[e-mail]"],
        "subject": "Hello from Mailisk",
        "text": "Plain text body",
        "html": "<p>HTML body</p>",
    },
)

print(email["id"], email["status"])

Send with an attachment:

import base64
from pathlib import Path

content = Path("report.txt").read_bytes()

mailisk.send_email(
    "mynamespace",
    {
        "to": ["[e-mail]"],
        "subject": "Report",
        "text": "Attached.",
        "attachments": [
            {
                "filename": "report.txt",
                "content_type": "application/octet-stream",
                "content_base64": base64.b64encode(content).decode("ascii"),
            }
        ],
    },
)

Fetch delivery details:

detail = mailisk.get_outbound_email(email["id"])
print(detail["delivery_summary"])

Reply to an inbound email:

reply = mailisk.reply_to_email(
    emails[0]["id"],
    {
        "subject": "Re: Thanks",
        "text": "We received your message.",
    },
)

Forward an inbound email:

forwarded = mailisk.forward_email(
    emails[0]["id"],
    {
        "to": ["[e-mail]"],
        "subject": "Fwd: Support request",
        "text": "Forwarding this along.",
    },
)

SMS

Search SMS messages:

messages = mailisk.search_sms_messages(
    "[phone]",
    {"from_number": "+1800555", "body": "Your code"},
)

List SMS numbers:

numbers = mailisk.list_sms_numbers()

Send a virtual SMS:

mailisk.send_virtual_sms(
    {
        "from_number": "[phone]",
        "to_number": "[phone]",
        "body": "Test message",
    }
)

TOTP

Create a saved TOTP device:

device = mailisk.create_totp_device(
    {
        "name": "GitHub staging",
        "shared_secret": "JBSWY3DPEHPK3PXP",
    }
)

Generate a TOTP code from a shared secret:

otp = mailisk.get_totp_otp_by_shared_secret(
    "JBSWY3DPEHPK3PXP",
    {"min_seconds_until_expire": 10},
)

print(otp["code"])

Generate a TOTP code for a saved device:

otp = mailisk.get_totp_otp_by_device_id(device["id"])

Delete a saved TOTP device:

mailisk.delete_totp_device(device["id"])

Development Checks

See DEVELOPMENT.md for local setup, .env configuration, and the live outbound smoke test.

python -m pytest
python -m mypy src tests
python -m build

Typing

The package includes py.typed and exports TypedDict/Literal types for API parameters and responses:

from mailisk import MailiskClient, SearchInboxResponse

client = MailiskClient(api_key="YOUR_API_KEY")
response: SearchInboxResponse = client.search_inbox("mynamespace")

You can import request and response types from mailisk directly, for example SendEmailParams, SearchInboxResponse, OutboundEmailResponse, OutboundEmailDetailResponse, and TotpOtpResponse.