From b5fed8b444dafcf6bf1954b3e7bad57ca68fb4b6 Mon Sep 17 00:00:00 2001 From: Hannes <31671206+xJuvi@users.noreply.github.com> Date: Thu, 4 Aug 2022 20:30:27 +0200 Subject: [PATCH 1/3] Replaces depracted functions mark functions to verify email addresses as depracted and add function to verify domains. Add a function to get all ConfigurationSets. Add functions to update account status and request the information about the accoutn status, add function to verify and manage dkim. --- src/SimpleEmailService.php | 247 +++++++++++++++++++++++++++++++++++++ 1 file changed, 247 insertions(+) diff --git a/src/SimpleEmailService.php b/src/SimpleEmailService.php index d970081..fab3a48 100644 --- a/src/SimpleEmailService.php +++ b/src/SimpleEmailService.php @@ -310,9 +310,51 @@ public function setBulkMode($enable = true) { $this->__bulk_sending_mode = (bool)$enable; return $this; } + + /** + * Lists all available configurationsets + * + * See: https://docs.aws.amazon.com/ses/latest/APIReference/API_ListConfigurationSets.html + * + * @param int $maxItems Number of configurationsets; max 1000 per request + * @param string $nextToken The token for the next request + * @return array An array containing three items: a list of configurationsets, the nextid and the request id. + */ + public function listConfigurationSets(?$maxItems, ?$nextToken) { + $ses_request = $this->getRequestHandler('POST'); + $ses_request->setParameter('Action', 'ListConfigurationSets'); + $ses_request->setParameter('MaxItems', $maxItems); + $ses_request->setParameter('NextToken', $nextToken); + + $ses_response = $ses_request->getResponse(); + if($ses_response->error === false && $ses_response->code !== 200) { + $ses_response->error = array('code' => $ses_response->code, 'message' => 'Unexpected HTTP status'); + } + if($ses_response->error !== false) { + $this->__triggerError('listConfigurationSets', $ses_response->error); + return false; + } + + $response = array(); + if(!isset($ses_response->body)) { + return $response; + } + + $addresses = array(); + foreach($ses_response->body->ListConfigurationSetsResult->ConfigurationSets->member as $configurationSet) { + $configurationSets[] = (string)$configurationSets; + } + + $response['ConfigurationSets'] = $configurationSets; + $response['NextToken'] = (string)$ses_response->body->ListConfigurationSetsResult->NextToken; + $response['RequestId'] = (string)$ses_response->body->ResponseMetadata->RequestId; + return $response; + } + /** * Lists the email addresses that have been verified and can be used as the 'From' address + * See: https://docs.aws.amazon.com/ses/latest/APIReference/API_ListVerifiedEmailAddresses.html * * @return array An array containing two items: a list of verified email addresses, and the request id. */ @@ -344,18 +386,133 @@ public function listVerifiedEmailAddresses() { return $response; } + + /* + * Enables or disables Easy DKIM signing of email sent from an identity. + * See: https://docs.aws.amazon.com/ses/latest/APIReference/API_SetIdentityDkimEnabled.html + * + * @param bool $dkimEnabled Sets whether DKIM signing is enabled for an identity. Set to true to enable DKIM signing for this identity; false to disable it. + * @param string $identity The identity for which DKIM signing should be enabled or disabled. + * @return array The request id for this request. + */ + public function setIdentityDkimEnabled(bool $dkimEnabled, string $identity) { + $ses_request = $this->getRequestHandler('POST'); + $ses_request->setParameter('Action', 'SetIdentityDkimEnabled'); + $ses_request->setParameter('DkimEnabled', $dkimEnabled); + $ses_request->setParameter('Identity', $identity; + + $ses_response = $ses_request->getResponse(); + if($ses_response->error === false && $ses_response->code !== 200) { + $ses_response->error = array('code' => $ses_response->code, 'message' => 'Unexpected HTTP status'); + } + if($ses_response->error !== false) { + $this->__triggerError('setIdentityDkimEnabled', $ses_response->error); + return false; + } + $response['RequestId'] = (string)$ses_response->body->ResponseMetadata->RequestId; + return $response; + } + /** + * Try to verify dkim from the given domain + * See: https://docs.aws.amazon.com/ses/latest/APIReference/API_VerifyDomainDkim.html + * + * @return array An array containing two items: a list the domain dkim tokens and the request id. + */ + public function verifyDomainDkim($domain) { + $ses_request = $this->getRequestHandler('POST'); + $ses_request->setParameter('Action', 'VerifyDomainDkim'); + $ses_request->setParameter('Domain', $domain); + + $ses_response = $ses_request->getResponse(); + if($ses_response->error === false && $ses_response->code !== 200) { + $ses_response->error = array('code' => $ses_response->code, 'message' => 'Unexpected HTTP status'); + } + if($ses_response->error !== false) { + $this->__triggerError('verifyDomainDkim', $ses_response->error); + return false; + } + + $response = array(); + if(!isset($ses_response->body)) { + return $response; + } + + $addresses = array(); + foreach($ses_response->body->VerifyDomainDkimResult->DkimTokens->member as $token) { + $tokens[] = (string)$token; + } + + $response['DkimTokens'] = $token; + $response['RequestId'] = (string)$ses_response->body->ResponseMetadata->RequestId; + + return $response; + } + + /* + * Enables or disables email sending across your entire Amazon SES account in the current AWS Region. + * See: https://docs.aws.amazon.com/ses/latest/APIReference/API_UpdateAccountSendingEnabled.html + * + * @param bool $enabled Describes whether email sending is enabled or disabled. + * @return array The request id for this request. + */ + public function updateAccountSendingEnabled(bool $enabled) { + $ses_request = $this->getRequestHandler('POST'); + $ses_request->setParameter('Action', 'UpdateAccountSendingEnabled'); + $ses_request->setParameter('Enabled', $enabled); + + $ses_response = $ses_request->getResponse(); + if($ses_response->error === false && $ses_response->code !== 200) { + $ses_response->error = array('code' => $ses_response->code, 'message' => 'Unexpected HTTP status'); + } + if($ses_response->error !== false) { + $this->__triggerError('updateAccountSendingEnabled', $ses_response->error); + return false; + } + + $response['RequestId'] = (string)$ses_response->body->ResponseMetadata->RequestId; + return $response; + } + + /* + * Returns the email sending status of the Amazon SES account. + * See: https://docs.aws.amazon.com/ses/latest/APIReference/API_GetAccountSendingEnabled.html + * + * @return array The request id for this request. + */ + public function getAccountSendingEnabled() { + $ses_request = $this->getRequestHandler('POST'); + $ses_request->setParameter('Action', 'GetAccountSendingEnabled'); + + $ses_response = $ses_request->getResponse(); + if($ses_response->error === false && $ses_response->code !== 200) { + $ses_response->error = array('code' => $ses_response->code, 'message' => 'Unexpected HTTP status'); + } + if($ses_response->error !== false) { + $this->__triggerError('getAccountSendingEnabled', $ses_response->error); + return false; + } + + $response['Enabled'] = (bool)$ses_response->body->GetAccountSendingEnabledResult->Enabled; + $response['RequestId'] = (string)$ses_response->body->ResponseMetadata->RequestId; + return $response; + } + + /** + * DEPRACTED * Requests verification of the provided email address, so it can be used * as the 'From' address when sending emails through SimpleEmailService. * * After submitting this request, you should receive a verification email * from Amazon at the specified address containing instructions to follow. + * See: https://docs.aws.amazon.com/ses/latest/APIReference/API_VerifyEmailAddress.html * * @param string $email The email address to get verified * @return array The request id for this request. */ public function verifyEmailAddress($email) { + $this->__triggerError('verifyEmailAddress', array('message' => 'Use the verifyEmailIdentity operation to verify a new email address.', 'depracted' => true)); $ses_request = $this->getRequestHandler('POST'); $ses_request->setParameter('Action', 'VerifyEmailAddress'); $ses_request->setParameter('EmailAddress', $email); @@ -372,14 +529,75 @@ public function verifyEmailAddress($email) { $response['RequestId'] = (string)$ses_response->body->ResponseMetadata->RequestId; return $response; } + + /** + * Requests verification of the provided email address, so it can be used + * as the 'From' address when sending emails through SimpleEmailService. + * + * After submitting this request, you should receive a verification email + * from Amazon at the specified address containing instructions to follow. + * See: https://docs.aws.amazon.com/ses/latest/APIReference/API_VerifyEmailIdentity.html + * + * @param string $email The email address to get verified + * @return array The request id for this request. + */ + public function verifyEmailIdentity(string $email) { + $ses_request = $this->getRequestHandler('POST'); + $ses_request->setParameter('Action', 'VerifyEmailIdentity'); + $ses_request->setParameter('EmailAddress', $email); + + $ses_response = $ses_request->getResponse(); + if($ses_response->error === false && $ses_response->code !== 200) { + $ses_response->error = array('code' => $ses_response->code, 'message' => 'Unexpected HTTP status'); + } + if($ses_response->error !== false) { + $this->__triggerError('verifyEmailIdentity', $ses_response->error); + return false; + } + + $response['RequestId'] = (string)$ses_response->body->ResponseMetadata->RequestId; + return $response; + } + + /** + * Requests verification of the provided domain, so all email addresses can used + * as the 'From' address when sending emails through SimpleEmailService. + * + * After submitting this request, you should verify the domain with by set a dns record. + * More information about domain varification are here: https://docs.aws.amazon.com/ses/latest/dg/verify-addresses-and-domains.html + * See: https://docs.aws.amazon.com/ses/latest/APIReference/API_VerifyDomainIdentity.html + * + * @param string $domain The domain to get verified + * @return array The request id for this request and the domain verification token. + */ + public function verifyDomainIdentity(string $domain) { + $ses_request = $this->getRequestHandler('POST'); + $ses_request->setParameter('Action', 'VerifyDomainIdentity'); + $ses_request->setParameter('Domain', $domain); + + $ses_response = $ses_request->getResponse(); + if($ses_response->error === false && $ses_response->code !== 200) { + $ses_response->error = array('code' => $ses_response->code, 'message' => 'Unexpected HTTP status'); + } + if($ses_response->error !== false) { + $this->__triggerError('domainIdentity', $ses_response->error); + return false; + } + + $response['RequestId'] = (string)$ses_response->body->ResponseMetadata->RequestId; + $response['VerificationToken'] = (string)$ses_response->body->VerifyDomainIdentityResult->VerificationToken; + return $response; + } /** + * DEPRACTED * Removes the specified email address from the list of verified addresses. * * @param string $email The email address to remove * @return array The request id for this request. */ public function deleteVerifiedEmailAddress($email) { + $this->__triggerError('deleteVerifiedEmailAddress', array('message' => 'Use the deleteIdentity operation to verify a new email address.', 'depracted' => true)); $ses_request = $this->getRequestHandler('DELETE'); $ses_request->setParameter('Action', 'DeleteVerifiedEmailAddress'); $ses_request->setParameter('EmailAddress', $email); @@ -396,6 +614,31 @@ public function deleteVerifiedEmailAddress($email) { $response['RequestId'] = (string)$ses_response->body->ResponseMetadata->RequestId; return $response; } + + /** + * Deletes the specified identity (an email address or a domain) from the list of verified identities. + * See https://docs.aws.amazon.com/ses/latest/APIReference/API_DeleteIdentity.html + * + * @param string $identity The identity to remove + * @return array The request id for this request. + */ + public function deleteIdentity(string $identity) { + $ses_request = $this->getRequestHandler('DELETE'); + $ses_request->setParameter('Action', 'DeleteIdentity'); + $ses_request->setParameter('Identity', $identity); + + $ses_response = $ses_request->getResponse(); + if($ses_response->error === false && $ses_response->code !== 200) { + $ses_response->error = array('code' => $ses_response->code, 'message' => 'Unexpected HTTP status'); + } + if($ses_response->error !== false) { + $this->__triggerError('deleteIdentity', $ses_response->error); + return false; + } + + $response['RequestId'] = (string)$ses_response->body->ResponseMetadata->RequestId; + return $response; + } /** * Retrieves information on the current activity limits for this account. @@ -603,6 +846,10 @@ public function __triggerError($functionname, $error) if($error == false) { trigger_error(sprintf("SimpleEmailService::%s(): Encountered an error, but no description given", $functionname), E_USER_WARNING); } + else if(isset($error['depracted'])) + { + trigger_error(sprintf("SimpleEmailService::%s(): %s", $functionname, $error['message']), E_USER_DEPRECATED); + } else if(isset($error['curl']) && $error['curl']) { trigger_error(sprintf("SimpleEmailService::%s(): %s %s", $functionname, $error['code'], $error['message']), E_USER_WARNING); From 0488334635ed8780c603d3ed97a8b95ef622d54e Mon Sep 17 00:00:00 2001 From: Hannes <31671206+xJuvi@users.noreply.github.com> Date: Thu, 4 Aug 2022 21:34:44 +0200 Subject: [PATCH 2/3] Update SimpleEmailService.php --- src/SimpleEmailService.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/SimpleEmailService.php b/src/SimpleEmailService.php index fab3a48..a0ec4f0 100644 --- a/src/SimpleEmailService.php +++ b/src/SimpleEmailService.php @@ -597,7 +597,7 @@ public function verifyDomainIdentity(string $domain) { * @return array The request id for this request. */ public function deleteVerifiedEmailAddress($email) { - $this->__triggerError('deleteVerifiedEmailAddress', array('message' => 'Use the deleteIdentity operation to verify a new email address.', 'depracted' => true)); + $this->__triggerError('deleteVerifiedEmailAddress', array('message' => 'Use the deleteIdentity operation to delete email addresses.', 'depracted' => true)); $ses_request = $this->getRequestHandler('DELETE'); $ses_request->setParameter('Action', 'DeleteVerifiedEmailAddress'); $ses_request->setParameter('EmailAddress', $email); From 83ff025512910a670862c0759096fdf97b1ea28e Mon Sep 17 00:00:00 2001 From: Hannes <31671206+xJuvi@users.noreply.github.com> Date: Fri, 5 Aug 2022 13:41:57 +0200 Subject: [PATCH 3/3] add changed functions Explain new functions and list depracted functions --- README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 45 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 461faa3..f5cad10 100644 --- a/README.md +++ b/README.md @@ -116,7 +116,7 @@ $m->addAttachmentFromFile('logo.png','path/to/logo.png','application/octet-strea // and use it in the html version of the e-mail: ``` -### Configuration Set and Message Tags +### Configuration Set, Message Tags, DKIM and Account sending status ```php setConfigurationSet('myConfigurationSet'); // Reset the configuration set $m->setConfigurationSet(null); +// List all created configuration sets +$m->listConfigurationSets($maxItems); + // Set message tag $m->setMessageTag('key', 'value'); @@ -145,6 +148,24 @@ $tags = $m->getMessageTags(); // Remove all message tags $m->removeMessageTags(); + +// Enables DKIM for domain example.com or email mail@example.com +$m->setIdentityDkimEnabled(true, 'example.com'); +$m->setIdentityDkimEnabled(true, 'mail@example.com'); + +// Disables DKIM for domain example.com or email mail@example.com +$m->setIdentityDkimEnabled(false, 'example.com'); +$m->setIdentityDkimEnabled(false, 'mail@example.com'); + +// Verify DKIM Tokens for given domain and return tokens +$m->verifyDomainDkim('example.com'); + +// Update sending status for global AWS account +$m->updateAccountSendingEnabled(true); // enabled +$m->updateAccountSendingEnabled(false); // disabled + +// get current sending status for global AWS account +$m->getAccountSendingEnabled(); ``` ### Sending Bulk Messages @@ -184,10 +205,18 @@ $ses = new SimpleEmailService('AccessKey', 'SecretKey', $region_endpoint); // Get the addresses that have been verified in your AWS SES account $ses->listVerifiedEmailAddresses(); -// Delete a verified address -$ses->deleteVerifiedEmailAddress('user@example.com'); + +// Delete a verified email address +$ses->deleteIdentity('user@example.com'); + +// Delete a verified domain +$ses->deleteIdentity('example.com'); + // Send a confirmation email in order to verify a new email -$ses->verifyEmailAddress('user@example.com'); +$ses->verifyEmailIdentity('user@example.com'); + +// Set domain as verified identitiy (note: You must set dns records) +$ses->verifyDomainIdentity('example.com'); // Get Send Quota $ses->getSendQuota(); @@ -225,7 +254,19 @@ $signature_version = SimpleEmailService::REQUEST_SIGNATURE_V4; $ses = new SimpleEmailService('AccessKey', 'SecretKey', $region_endpoint, $trigger_error, $signature_version); ``` +### Depracted functions +AWS depracts some function if the logic will be renewed. The following functions are marked as depracted all will be removed in a future version. Currently the functions will work but creates a "DEPRACTED" notice in the php. +```php +verifyEmailAddress('user@example.com'); + +// Delete a verified email address. +// "SimpleEmailService::deleteVerifiedEmailAddress(): Use the SimpleEmailService::deleteIdentity() operation to delete a verified email address." +$ses->deleteVerifiedEmailAddress('user@example.com'); +``` ### Changelog