From c98bed8f1998ea04c5b36e9790d5484b741dd0d5 Mon Sep 17 00:00:00 2001 From: Ente Date: Wed, 15 Apr 2026 15:13:58 +0200 Subject: [PATCH 1/2] feat: adding Endpoints as of 2026-03a --- src/Aliases/Aliases.php | 23 +++++++++++++ src/AntiSpam/AntiSpam.php | 2 +- src/Domains/Domains.php | 11 +++++++ src/MailCowAPI.php | 15 +++++++++ src/Mailboxes/MailBoxes.php | 61 +++++++++++++++++++++++++++++++++-- src/SyncJobs/SyncJobs.php | 64 +++++++++++++++++++++++++++++++++++++ 6 files changed, 173 insertions(+), 3 deletions(-) create mode 100644 src/SyncJobs/SyncJobs.php diff --git a/src/Aliases/Aliases.php b/src/Aliases/Aliases.php index 86dd08c..44fb6c5 100644 --- a/src/Aliases/Aliases.php +++ b/src/Aliases/Aliases.php @@ -25,6 +25,15 @@ public function getAliases() return $this->MailCowAPI->get('get/alias/all'); } + /** + * `getTimeLimitedAliases()` - Returns all time-limited aliases for given mailbox + * @param string $mailboxId The mailbox ID to filter time-limited aliases for + * @return array|string + */ + public function getTimeLimitedAliases(string $mailboxId){ + return $this->MailCowAPI->get('get/alias/time_limited_aliases/' . $mailboxId); + } + /** * `getAliasesByDomain()` - Returns all aliases for a specific domain * @param string $domain The domain name @@ -57,6 +66,20 @@ public function getAlias(string $aliasID) return $this->MailCowAPI->get('get/alias/' . $aliasID); } + /** + * `createTimeLimitedAlias()` - Creates a time-limited alias for given mailbox + * @param string $mailboxId The mailbox ID to create the time-limited alias for + * @param string $domain The domain for the alias + * @return array|string + */ + public function createTimeLimitedAlias(string $mailboxId, string $domain) + { + return $this->MailCowAPI->post('add/time_limited_alias', [ + 'username' => $mailboxId, + 'domain' => $domain + ]); + } + /** * `createAlias()` - Creates a new alias * @param string $alias_address The alias name (full email address) diff --git a/src/AntiSpam/AntiSpam.php b/src/AntiSpam/AntiSpam.php index 00e597a..93eef8c 100644 --- a/src/AntiSpam/AntiSpam.php +++ b/src/AntiSpam/AntiSpam.php @@ -55,7 +55,7 @@ public function addPolicy(string $domain, string $object_list, string $object_fr /** * `deletePolicy()` - Deletes a domain policy - * @param string $PolicyID The policy ID to delete + * @param array $PolicyID The policy ID to delete * @return array|string */ public function deletePolicy(array $PolicyID) diff --git a/src/Domains/Domains.php b/src/Domains/Domains.php index 52b1a26..bfb462b 100644 --- a/src/Domains/Domains.php +++ b/src/Domains/Domains.php @@ -163,4 +163,15 @@ public function updateFooter(string $domain, string $html, string $plain, ?array ] ]); } + + /** + * `deleteDomainTag()` - Deletes given domain tag + * @param string $domain The domain name to delete the tag from + * @param array $tags The tags to delete + * @return array|string + * + */ + public function deleteDomainTag(string $domain, array $tags){ + return $this->MailCowAPI->post('delete/domain/tag/' . urlencode($domain), $tags); + } } \ No newline at end of file diff --git a/src/MailCowAPI.php b/src/MailCowAPI.php index bf0b023..dbc2455 100644 --- a/src/MailCowAPI.php +++ b/src/MailCowAPI.php @@ -26,6 +26,7 @@ use Exbil\Mailcow\SSO\SSO; use Exbil\Mailcow\CORS\CORS; use Exbil\Mailcow\IdentityProvider\IdentityProvider; +use Exbil\Mailcow\SyncJobs\SyncJobs; use Psr\Http\Message\ResponseInterface; class MailCowAPI @@ -58,6 +59,7 @@ class MailCowAPI private ?SSO $SSOHandler = null; private ?CORS $CORSHandler = null; private ?IdentityProvider $IdentityProviderHandler = null; + private ?SyncJobs $syncJobsHandler = null; /** * MailCowAPI constructor. @@ -556,4 +558,17 @@ public function IdentityProvider(): IdentityProvider } return $this->IdentityProviderHandler; } + + /** + * Get SyncJobs handler + * + * @return SyncJobs + */ + public function syncJobs(): SyncJobs + { + if (!$this->syncJobsHandler) { + $this->syncJobsHandler = new SyncJobs($this); + } + return $this->syncJobsHandler; + } } \ No newline at end of file diff --git a/src/Mailboxes/MailBoxes.php b/src/Mailboxes/MailBoxes.php index d9b827e..8f89c13 100644 --- a/src/Mailboxes/MailBoxes.php +++ b/src/Mailboxes/MailBoxes.php @@ -184,14 +184,24 @@ public function updateMailboxSpamScore(string $email, string $score) ]); } + /** + * `getMailboxSpamScore()` - Return the mailbox' spam score + * @param string $email The mailbox to query + * @return array|string + */ + + public function getMailboxSpamScore(string $email){ + return $this->MailCowAPI->get('get/spam-score/' . urlencode($email)); + } + /** * `deleteMailBox()` - Delete given mailbox * @param string $mails The mailbox to delete * @return array|string */ - public function deleteMailBox(array $mails) + public function deleteMailBox(string $mails) { - return $this->MailCowAPI->post('delete/mailbox', $mails); + return $this->MailCowAPI->post('delete/mailbox', [$mails]); } /** @@ -223,4 +233,51 @@ public function editPushoverSettings(string $username, bool $active, int $evalua "items" => $username ]); } + + /** + * `editMailboxACL` - Edits the given mailbox' ACL + * @param string $mailbox The mailbox to edit the ACL for + * @param array $acl The ACL to set, e.g. ["spam_alias", "eas_reset", "quarantine", ...] + * @return array|string + */ + public function editMailboxACL(string $mailbox, array $acl){ + return $this->MailCowAPI->post('edit/mailbox-acl', [ + "items" => $mailbox, + "attr" => [ + "user_acl" => $acl + ] + ]); + } + + /** + * `updateMailboxQuarantineNotification` - Update the quarantine notification settings for given mailbox + * @param string $mailbox The mailbox to edit the quarantine notification settings for + * @param array $anyOf Include these items in the notifications, e.g. acme@inc.com + * @param string $notifyTime The time frame for the notifications, e.g. "hourly" + * @return array|string + */ + public function updateMailboxQuarantineNotification(string $mailbox, array $anyOf, string $notifyTime = "hourly"){ + return $this->MailCowAPI->post('edit/quarantine-notification', [ + "items" => $mailbox, + "attr" => [ + "any_of" => $anyOf + ], + "quarantine_notification" => $notifyTime + ]); + } + + /** + * `updateMailboxCustomAttributes()` - Update custom attributes for given mailbox + * @param string $mailbox The mailbox to edit the custom attributes for + * @param array $attributes The attributes to update, e.g. ["custom1", "custom2", ...] + * @param array $value The values to set for the attributes, e.g. ["value1", "value2", ...] + * @return array|string + */ + public function updateMailboxCustomAttributes(string $mailbox, array $attributes, array $value){ + return $this->MailCowAPI->post('edit/mailbox', [ + "items" => $mailbox, + "attribute" => $attributes, + "value" => $value + ]); + } } \ No newline at end of file diff --git a/src/SyncJobs/SyncJobs.php b/src/SyncJobs/SyncJobs.php new file mode 100644 index 0000000..21c8d0d --- /dev/null +++ b/src/SyncJobs/SyncJobs.php @@ -0,0 +1,64 @@ +MailCowAPI = $MailCowAPI; + } + + /** + * `createSyncJob()` - Creates a new sync job + * @param string $username The username of the local mailbox to sync to + * @param string $host1 The remote host to sync from, e.g. mail.acme.inc + * @param string $port1 The remote port to sync from, e.g. 993/143 + * @param string $user1 The remote user to sync from, e.g. "john.doe@acme.inc" + * @param string $pass1 The remote password needed for authentication + * @param bool $active Whether the sync job should be active right after creation + * @param bool $dryRun Whether the sync job should be executed as a dry run, meaning that no changes will be made to the local or remote mailbox. This is useful for testing the connection and settings of the sync job without actually syncing any emails. + * @param string $enc The encryption method to use for the connection, e.g. "TLS", "SSL" or "STARTTLS" + * @param int $mins_interval The interval in minutes at which the sync job should run + * @param int $maxage The maximum age of emails to sync in days, e.g. 30. Emails older than this will not be synced. Set to 0 to sync all emails regardless of age. + * @param int $timeouts The timeout in seconds for the connection to the remote mail server, e.g. 600 + * @param string $exclude A regular expression pattern to exclude certain emails from being synced based on their subject or sender, e.g. "(?i)spam|(?i)junk" to exclude emails with "spam" or "junk" in the subject or sender. Set to an empty string to not exclude any emails. + * @param bool $deleteDuplicatesOnMailcow Whether to delete duplicate emails on Mailcow that are also present on the remote mailbox. This can help save storage space on Mailcow, but may result in data loss if not used carefully. Set to true to enable this option, or false to keep duplicate emails on Mailcow. + * @param bool $deleteFromRemote Whether to delete emails from the remote mailbox after they have been synced to Mailcow. This can help keep the remote mailbox clean, but may result in data loss if not used carefully. Set to true to enable this option, or false to keep emails on the remote mailbox after syncing. + * @param bool $automap Whether to automatically map the remote mailbox' contents into the local mailbox' folders. If set to true, the sync job will try to match the remote mailbox' folders with the local mailbox' folders and sync emails accordingly. If set to false, all synced emails will be placed in the local mailbox' inbox, regardless of their original folder on the remote mailbox. + * @return array|string + */ + public function createSyncJob(string $username, string $host1, string $port1, string $user1, string $pass1, bool $active = false, bool $dryRun = true, string $enc = "TLS", int $mins_interval = 20, int $maxage = 0, int $timeouts = 600, string $exclude = "(?i)spam|(?i)junk", bool $deleteDuplicatesOnMailcow = true, bool $deleteFromRemote = false, bool $automap = true){ + return $this->MailCowAPI->post('add/syncjob', [ + "active" => $active ? 1 : 0, + "username" => $username, + "host1" => $host1, + "port1" => $port1, + "user1" => $user1, + "pass1" => $pass1, + "enc" => $enc, + "mins_interval" => $mins_interval, + "maxage" => $maxage, + "timeouts" => $timeouts, + "exclude" => $exclude, + "deleteDuplicatesOnMailcow" => $deleteDuplicatesOnMailcow ? 1 : 0, + "deleteFromRemote" => $deleteFromRemote ? 1 : 0, + "automap" => $automap ? 1 : 0, + "dryRun" => $dryRun ? 1 : 0 + ]); + } + + /** + * `deleteSyncJob()` - Deletes one or multiple Sync Job + * @param array $ids An array of IDs of the sync jobs to delete, e.g. [1, 2, 3] + * @return array|string + */ + public function deleteSyncJob(array $ids){ + return $this->MailCowAPI->post('delete/syncjob', $ids); + } + + public function getAllSyncJobs(){ + return $this->MailCowAPI->get('get/syncjobs/all/no_log'); + } +} \ No newline at end of file From a6c6cdb0795a484375034f308f1bfceb15714259 Mon Sep 17 00:00:00 2001 From: Ente Date: Tue, 21 Apr 2026 23:17:29 +0200 Subject: [PATCH 2/2] Documentation and API endpoint enhancements --- src/Domains/Domains.php | 39 +++++++++++++++++++++++-------------- src/Mailboxes/MailBoxes.php | 22 +++++++++++++++++---- 2 files changed, 42 insertions(+), 19 deletions(-) diff --git a/src/Domains/Domains.php b/src/Domains/Domains.php index bfb462b..4c3b2fb 100644 --- a/src/Domains/Domains.php +++ b/src/Domains/Domains.php @@ -29,27 +29,34 @@ public function getDomains() /** * `getDomain()` - Returns the configuration of given domain + * @param string $domain The domain name to retrieve the configuration for + * @param ?array $tags Optional array of tags to filter the domains by * @return array|string */ - public function getDomain(string $domain) + public function getDomain(string $domain, ?array $tags = null) { - return $this->MailCowAPI->get('get/domain/' . $domain); + $url = 'get/domain/' . $domain; + if ($tags !== null) { + $url .= '?' . http_build_query(['tags' => $tags]); + } + return $this->MailCowAPI->get($url); } /** * `addDomain()` - Creates a new domain - * @param string $domain Domain name, z.B. 'mailcow.tld' - * @param string $description Beschreibung der Domain - * @param int $aliases Maximalanzahl an Aliases - * @param int $mailboxes Maximalanzahl an Mailboxen + * @param string $domain Domain name, e.g.. 'mailcow.tld' + * @param string $description Description for the domain + * @param int $aliases Maximum amount of aliases allowed for this domain + * @param int $mailboxes Maximum amount of mailboxes allowed for this domain * @param int $defquota Standard-Quota in MB - * @param int $maxquota Maximal-Quota in MB - * @param int $active 1 = aktiv, 0 = deaktiviert - * @param int $rl_value Rate-Limit Wert - * @param string $rl_frame Rate-Limit Zeitrahmen, z.B. 's', 'm' - * @param int $backupmx Backup-MX aktiv (1) oder nicht (0) - * @param int $relay_all_recipients 1 = alle Empfänger durchreichen, 0 = nicht - * @param int $restart_sogo 1 = SOGo neu starten, 0 = nicht + * @param int $maxquota Maximum-Quota in MB + * @param int $active 1 = aktiv, 0 = disabled + * @param int $rl_value Rate-Limit Value + * @param string $rl_frame Rate-Limit Time frame, e.g. 's', 'm' + * @param int $backupmx Enable (1) or disable (0) Backup-MX + * @param int $relay_all_recipients 1 = relay all recipients, 0 = do not relay all recipients + * @param int $restart_sogo 1 = Restart SoGO, 0 = do not restart SOGO, + * @param ?array $tags Optional array of tags to assign to the domain * @return array|string */ public function addDomain( @@ -64,7 +71,8 @@ public function addDomain( string $rl_frame = "s", int $backupmx = 0, int $relay_all_recipients = 0, - int $restart_sogo = 1 + int $restart_sogo = 1, + ?array $tags = null ) { $payload = [ "domain" => $domain, @@ -79,7 +87,8 @@ public function addDomain( "rl_frame" => $rl_frame, "backupmx" => $backupmx, "relay_all_recipients" => $relay_all_recipients, - "restart_sogo" => $restart_sogo + "restart_sogo" => $restart_sogo, + "tags" => $tags ]; return $this->MailCowAPI->post('add/domain', $payload); diff --git a/src/Mailboxes/MailBoxes.php b/src/Mailboxes/MailBoxes.php index 8f89c13..10ad04a 100644 --- a/src/Mailboxes/MailBoxes.php +++ b/src/Mailboxes/MailBoxes.php @@ -69,7 +69,9 @@ public function addMailBox( string $quota = "1024", bool $tls_enforce_in = true, bool $tls_enforce_out = true, - bool $sogo_access = true + bool $sogo_access = true, + ?string $authsource = null, + ?string $tags = null ) { return $this->MailCowAPI->post('add/mailbox', [ 'local_part' => $mailname, @@ -83,6 +85,8 @@ public function addMailBox( 'tls_enforce_in' => $tls_enforce_in ? '1' : '0', 'tls_enforce_out' => $tls_enforce_out ? '1' : '0', 'sogo_access' => $sogo_access ? '1' : '0', + 'authsource' => $authsource ?? 'mailcow', + 'tags' => $tags ?? '', ]); } @@ -196,12 +200,12 @@ public function getMailboxSpamScore(string $email){ /** * `deleteMailBox()` - Delete given mailbox - * @param string $mails The mailbox to delete + * @param array $mails The mailbox(es) to delete * @return array|string */ - public function deleteMailBox(string $mails) + public function deleteMailBox(array $mails) { - return $this->MailCowAPI->post('delete/mailbox', [$mails]); + return $this->MailCowAPI->post('delete/mailbox', $mails); } /** @@ -280,4 +284,14 @@ public function updateMailboxCustomAttributes(string $mailbox, array $attributes "value" => $value ]); } + + /** + * `deleteMailboxTags()` - Delete tags from given mailbox + * @param string $mailbox The mailbox to delete the tags from + * @param array $tags The tags to delete, e.g. ["tag1", "tag2", ...] + * @return array|string + */ + public function deleteMailboxTags(string $mailbox, array $tags){ + return $this->MailCowAPI->post('delete/mailbox/tags/' . $mailbox, $tags); + } } \ No newline at end of file