vielhuber/mailhelper

Lightweight email integration layer.

Maintainers

Details

github.com/vielhuber/mailhelper

Source

Issues

Installs: 7

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 0

Forks: 0

Open Issues: 0

pkg:composer/vielhuber/mailhelper

1.1.6 2025-11-27 10:31 UTC

Requires

MIT 61cb4370121195cc5812de07a4f152ede8533ad2

This package is auto-updated.

Last update: 2025-11-27 10:31:52 UTC

README

mailhelper is a lightweight email integration layer on top of phpmailer and php-imap that provides a simple cli, php wrapper, and mcp server for fetching messages, sending emails, and wiring email functionality into existing tooling without having to deal with complex imap/smtp configuration yourself.

requirements

  • php >= 8.1

installation

composer

composer require vielhuber/mailhelper

create config

vi config.json
{
    "info@example.com": {
        "imap": {
            "host": "imap.example.com",
            "port": 993,
            "username": "info@example.com",
            "password": "***",
            "encryption": "ssl"
        },
        "smtp": {
            "host": "smtp.example.com",
            "port": 465,
            "username": "info@example.com",
            "password": "***",
            "encryption": "ssl"
        }
    },
    "support@company.com": {
        "imap": {
            "host": "outlook.office365.com",
            "port": 993,
            "client_id": "***",
            "client_secret": "***",
            "tenant_id": "***",
            "encryption": "tls"
        },
        "smtp": {
            "host": "smtp.company.com",
            "port": 465,
            "username": "support@company.com",
            "password": "***",
            "encryption": "ssl"
        }
    }
}

usage

cli

./vendor/bin/mailhelper.php fetch \
    --mailbox "xxx@tld.com" \
    --folder "INBOX/foo/bar" \
    --filter-date-from "YYYY-MM-DD HH:II:SS" \
    --filter-date-until "YYYY-MM-DD HH:II:SS" \
    --filter-subject "pattern" \
    --filter-message "pattern" \
    --filter-to "pattern" \
    --filter-cc "pattern" \
    --limit 42 \
    --order "desc"

./vendor/bin/mailhelper.php send \
    --mailbox "xxx@tld.com" \
    --subject "This is a test! 🚀" \
    --message "✅ Test <strong>successful</strong>!" \
    --from-name "John Doe",
    --to "aaa@tld.com" \
    --to '["aaa@tld.com", "bbb@tld.com"]' \
    --to '[{"name": "John Doe", "email": "aaa@tld.com"}, {"name": "Jane Doe", "email": "bbb@tld.com"}]' \
    --cc "aaa@tld.com" \
    --bcc "aaa@tld.com" \
    --attachments: "/test1.jpg" \
    --attachments: '["/test1.jpg", "/test2.jpg"]' \
    --attachments: '[{"name": "foo1.jpg", "file": "/test1.jpg"}, {"name": "foo2.jpg", "file": "/test2.jpg"}]'

./vendor/bin/mailhelper.php folders \
    --mailbox "xxx@tld.com"

./vendor/bin/mailhelper.php view \
    --mailbox "xxx@tld.com" \
    --folder "INBOX/foo/bar" \
    --id "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

./vendor/bin/mailhelper.php edit \
    --mailbox "xxx@tld.com" \
    --folder "INBOX/foo/bar" \
    --id "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    --move "INBOX/foo/bar" \
    --delete \
    --read \
    --unread

php

require_once __DIR__ . '/vendor/autoload.php';
use vielhuber\mailhelper\mailhelper;

mailhelper::fetch(
    mailbox: 'xxx@tld.com',
    folder: 'INBOX/foo/bar',
    filter: [
        'date_from' => date('Y-m-d H:i:s', strtotime('now - 1 hour')),
        'date_until' => date('Y-m-d H:i:s', strtotime('now')),
        'subject' => 'pattern',
        'message' => 'pattern'
        'to' => 'pattern',
        'cc' => 'pattern'
    ],
    limit: 42,
    order: 'asc'
);

mailhelper::send(
    mailbox: 'xxx@tld.com',
    subject: 'This is a test! 🚀',
    message: '✅ Test <strong>successful</strong>!',
    from_name: 'John Doe',
    to: 'aaa@tld.com',
    to: ['aaa@tld.com', 'bbb@tld.com'],
    to: [['name' => 'John Doe', 'email' => 'aaa@tld.com'], ['name' => 'Jane Doe', 'email' => 'bbb@tld.com']],
    cc: 'aaa@tld.com',
    bcc: 'aaa@tld.com',
    attachments: __DIR__ . '/test1.jpg',
    attachments: [__DIR__ . '/test1.jpg', __DIR__ . '/test2.jpg'],
    attachments: [
        ['name' => 'foo1.jpg', 'file' => __DIR__ . '/test1.jpg'],
        ['name' => 'foo2.jpg', 'file' => __DIR__ . '/test2.jpg']
    ]
);

mailhelper::folders(
    mailbox: 'xxx@tld.com'
);

mailhelper::view(
    mailbox: 'xxx@tld.com',
    folder: 'INBOX/foo/bar',
    id: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
);

mailhelper::edit(
    mailbox: 'xxx@tld.com',
    folder: 'INBOX/foo/bar',
    id: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    move: 'INBOX/foo/bar',
    delete: true,
    read: true,
    unread: true
);

mcp

{
    "mcpServers": {
        "email": {
            "command": "/usr/bin/php8.1",
            "args": ["/var/www/project/vendor/vielhuber/mailhelper/src/mcp.php"]
        }
    }
}