{"id":13616577,"url":"https://github.com/ddeboer/imap","last_synced_at":"2025-05-13T18:07:20.020Z","repository":{"id":4071994,"uuid":"5176656","full_name":"ddeboer/imap","owner":"ddeboer","description":"Object-oriented, fully tested PHP IMAP library","archived":false,"fork":false,"pushed_at":"2025-02-17T14:22:02.000Z","size":849,"stargazers_count":907,"open_issues_count":74,"forks_count":252,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-04-25T14:50:39.821Z","etag":null,"topics":["email","imap","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ddeboer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["ddeboer","Slamdunk"]}},"created_at":"2012-07-25T08:34:38.000Z","updated_at":"2025-04-22T21:18:18.000Z","dependencies_parsed_at":"2023-07-05T21:16:32.990Z","dependency_job_id":"1d56f72c-33d7-47f4-8507-00cf70961ce5","html_url":"https://github.com/ddeboer/imap","commit_stats":{"total_commits":465,"total_committers":61,"mean_commits":7.622950819672131,"dds":0.4666666666666667,"last_synced_commit":"efc1455d26235320694192eba5ebeabf8484a9a4"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddeboer%2Fimap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddeboer%2Fimap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddeboer%2Fimap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddeboer%2Fimap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ddeboer","download_url":"https://codeload.github.com/ddeboer/imap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254000848,"owners_count":21997441,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email","imap","php"],"created_at":"2024-08-01T20:01:30.374Z","updated_at":"2025-05-13T18:07:19.986Z","avatar_url":"https://github.com/ddeboer.png","language":"PHP","funding_links":["https://github.com/sponsors/ddeboer","https://github.com/sponsors/Slamdunk"],"categories":["PHP","目录","Table of Contents"],"sub_categories":["电子邮件 Email","Email"],"readme":"# PHP IMAP library\n\n[![Latest Stable Version](https://img.shields.io/packagist/v/ddeboer/imap.svg)](https://packagist.org/packages/ddeboer/imap)\n[![Downloads](https://img.shields.io/packagist/dt/ddeboer/imap.svg)](https://packagist.org/packages/ddeboer/imap)\n[![Integrate](https://github.com/ddeboer/imap/workflows/CI/badge.svg)](https://github.com/ddeboer/imap/actions)\n[![Code Coverage](https://codecov.io/gh/ddeboer/imap/coverage.svg?branch=master)](https://codecov.io/gh/ddeboer/imap?branch=master)\n\nA PHP IMAP library to read and process e-mails over IMAP protocol, built with robust Object-Oriented architecture.\n\nThis library requires PHP \u003e= 8.3 with [IMAP](https://www.php.net/manual/en/book.imap.php),\n[iconv](https://www.php.net/manual/en/book.iconv.php) and\n[Multibyte String](https://www.php.net/manual/en/book.mbstring.php) extensions installed.\n\n## Installation\n\nThe recommended way to install the IMAP library is through [Composer](https://getcomposer.org):\n\n```bash\n$ composer require ddeboer/imap\n```\n\nThis command requires you to have Composer installed globally, as explained\nin the [installation chapter](https://getcomposer.org/doc/00-intro.md)\nof the Composer documentation.\n\n## Usage\n\n### Connect and Authenticate\n\n```php\nuse Ddeboer\\Imap\\Server;\n\n$server = new Server('imap.gmail.com');\n\n// $connection is instance of \\Ddeboer\\Imap\\Connection\n$connection = $server-\u003eauthenticate('my_username', 'my_password');\n```\n\nYou can specify port, [flags and parameters](https://secure.php.net/manual/en/function.imap-open.php)\nto the server:\n\n```php\n$server = new Server(\n    $hostname, // required\n    $port,     // defaults to '993'\n    $flags,    // defaults to '/imap/ssl/validate-cert'\n    $parameters\n);\n```\n\n### Mailboxes\n\nRetrieve mailboxes (also known as mail folders) from the mail server and iterate\nover them:\n\n```php\n$mailboxes = $connection-\u003egetMailboxes();\n\nforeach ($mailboxes as $mailbox) {\n    // Skip container-only mailboxes\n    // @see https://secure.php.net/manual/en/function.imap-getmailboxes.php\n    if ($mailbox-\u003egetAttributes() \u0026 \\LATT_NOSELECT) {\n        continue;\n    }\n\n    // $mailbox is instance of \\Ddeboer\\Imap\\Mailbox\n    printf('Mailbox \"%s\" has %s messages', $mailbox-\u003egetName(), $mailbox-\u003ecount());\n}\n```\n\nOr retrieve a specific mailbox:\n\n```php\n$mailbox = $connection-\u003egetMailbox('INBOX');\n```\n\nDelete a mailbox:\n\n```php\n$connection-\u003edeleteMailbox($mailbox);\n```\n\nYou can bulk set, or clear, any [flag](https://secure.php.net/manual/en/function.imap-setflag-full.php) of mailbox messages (by UIDs):\n\n```php\n$mailbox-\u003esetFlag('\\\\Seen \\\\Flagged', ['1:5', '7', '9']);\n$mailbox-\u003esetFlag('\\\\Seen', '1,3,5,6:8');\n\n$mailbox-\u003eclearFlag('\\\\Flagged', '1,3');\n```\n\n**WARNING** You must retrieve new Message instances in case of bulk modify flags to refresh the single Messages flags.\n\n### Messages\n\nRetrieve messages (e-mails) from a mailbox and iterate over them:\n\n```php\n$messages = $mailbox-\u003egetMessages();\n\nforeach ($messages as $message) {\n    // $message is instance of \\Ddeboer\\Imap\\Message\n}\n```\n\nTo insert a new message (that just has been sent) into the Sent mailbox and flag it as seen:\n\n```php\n$mailbox = $connection-\u003egetMailbox('Sent');\n$mailbox-\u003eaddMessage($messageMIME, '\\\\Seen');\n```\n\nNote that the message should be a string at MIME format (as described in the [RFC2045](https://tools.ietf.org/html/rfc2045)).\n\n#### Searching for Messages\n\n```php\nuse Ddeboer\\Imap\\SearchExpression;\nuse Ddeboer\\Imap\\Search\\Email\\To;\nuse Ddeboer\\Imap\\Search\\Text\\Body;\n\n$search = new SearchExpression();\n$search-\u003eaddCondition(new To('me@here.com'));\n$search-\u003eaddCondition(new Body('contents'));\n\n$messages = $mailbox-\u003egetMessages($search);\n```\n\n**WARNING** We are currently unable to have both spaces _and_ double-quotes\nescaped together. Only spaces are currently escaped correctly.\nYou can use `Ddeboer\\Imap\\Search\\RawExpression` to write the complete search\ncondition by yourself.\n\nMessages can also be retrieved sorted as per [imap_sort](https://secure.php.net/manual/en/function.imap-sort.php)\nfunction:\n\n```php\n$today = new DateTimeImmutable();\n$thirtyDaysAgo = $today-\u003esub(new DateInterval('P30D'));\n\n$messages = $mailbox-\u003egetMessages(\n    new Ddeboer\\Imap\\Search\\Date\\Since($thirtyDaysAgo),\n    \\SORTDATE, // Sort criteria\n    true // Descending order\n);\n```\n\n#### Unknown search criterion: OR\n\nNote that PHP imap library relies on the `c-client` library available at https://www.washington.edu/imap/\nwhich doesn't fully support some IMAP4 search criteria like `OR`. If you want those unsupported criteria,\nyou need to manually patch the latest version (`imap-2007f` of 23-Jul-2011 at the time of this commit)\nand recompile PHP onto your patched `c-client` library.\n\nBy the way most of the common search criteria are available and functioning, browse them in `./src/Search`.\n\nReferences:\n\n1. https://stackoverflow.com/questions/36356715/imap-search-unknown-search-criterion-or\n2. imap-2007f.tar.gz: `./src/c-client/mail.c` and `./docs/internal.txt`\n\n#### Message Properties and Operations\n\nGet message number and unique [message id](https://en.wikipedia.org/wiki/Message-ID)\nin the form \u003c...\u003e:\n\n```php\n$message-\u003egetNumber();\n$message-\u003egetId();\n```\n\nGet other message properties:\n\n```php\n$message-\u003egetSubject();\n$message-\u003egetFrom();    // Message\\EmailAddress\n$message-\u003egetTo();      // array of Message\\EmailAddress\n$message-\u003egetDate();    // DateTimeImmutable\n$message-\u003eisAnswered();\n$message-\u003eisDeleted();\n$message-\u003eisDraft();\n$message-\u003eisSeen();\n```\n\nGet message headers as a [\\Ddeboer\\Imap\\Message\\Headers](/src/Message/Headers.php) object:\n\n```php\n$message-\u003egetHeaders();\n```\n\nGet message body as HTML or plain text (only first part):\n\n```php\n$message-\u003egetBodyHtml();    // Content of text/html part, if present\n$message-\u003egetBodyText();    // Content of text/plain part, if present\n```\n\n\nGet complete body (all parts):\n\n```php\n$body = $message-\u003egetCompleteBodyHtml();    // Content of text/html part, if present\nif ($body === null) { // If body is null, there are no HTML parts, so let's try getting the text body\n    $body = $message-\u003egetCompleteBodyText();    // Content of text/plain part, if present\n}\n```\n\nReading the message body keeps the message as unseen.\nIf you want to mark the message as seen:\n\n```php\n$message-\u003emarkAsSeen();\n```\n\nOr you can set, or clear, any [flag](https://secure.php.net/manual/en/function.imap-setflag-full.php):\n\n```php\n$message-\u003esetFlag('\\\\Seen \\\\Flagged');\n$message-\u003eclearFlag('\\\\Flagged');\n```\n\nMove a message to another mailbox:\n\n```php\n$mailbox = $connection-\u003egetMailbox('another-mailbox');\n$message-\u003emove($mailbox);\n```\n\nDeleting messages:\n\n```php\n$mailbox-\u003egetMessage(1)-\u003edelete();\n$mailbox-\u003egetMessage(2)-\u003edelete();\n$connection-\u003eexpunge();\n```\n\n### Message Attachments\n\nGet message attachments (both inline and attached) and iterate over them:\n\n```php\n$attachments = $message-\u003egetAttachments();\n\nforeach ($attachments as $attachment) {\n    // $attachment is instance of \\Ddeboer\\Imap\\Message\\Attachment\n}\n```\n\nDownload a message attachment to a local file:\n\n```php\n// getDecodedContent() decodes the attachment’s contents automatically:\nfile_put_contents(\n    '/my/local/dir/' . $attachment-\u003egetFilename(),\n    $attachment-\u003egetDecodedContent()\n);\n```\n\n### Embedded Messages\n\nCheck if attachment is embedded message and get it:\n\n```php\n$attachments = $message-\u003egetAttachments();\n\nforeach ($attachments as $attachment) {\n    if ($attachment-\u003eisEmbeddedMessage()) {\n        $embeddedMessage = $attachment-\u003egetEmbeddedMessage();\n        // $embeddedMessage is instance of \\Ddeboer\\Imap\\Message\\EmbeddedMessage\n    }\n}\n```\n\nAn EmbeddedMessage has the same API as a normal Message, apart from flags\nand operations like copy, move or delete.\n\n### Timeouts\n\nThe IMAP extension provides the [imap_timeout](https://secure.php.net/manual/en/function.imap-timeout.php)\nfunction to adjust the timeout seconds for various operations.\n\nHowever the extension's implementation doesn't link the functionality to a\nspecific context or connection, instead they are global. So in order to not\naffect functionalities outside this library, we had to choose whether wrap\nevery `imap_*` call around an optional user-provided timeout or leave this\ntask to the user.\n\nBecause of the heterogeneous world of IMAP servers and the high complexity\nburden cost for such a little gain of the former, we chose the latter.\n\n## Mock the library\n\nMockability is granted by interfaces present for each API.\nDig into [MockabilityTest](tests/MockabilityTest.php) for an example of a\nmocked workflow.\n\n## Contributing: run the build locally\n\nDocker is needed to run the build on your computer.\n\nFirst command you need to run is `make start-imap-server`, which starts an IMAP server locally.\n\nThen the local build can be triggered with a bare `make`.\n\nWhen you finish the development, stop the local IMAP server with `make stop-imap-server`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddeboer%2Fimap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fddeboer%2Fimap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddeboer%2Fimap/lists"}