Pmk 524b

src/Postmark/PostmarkClient.php

@@ -62,35 +62,35 @@ public function __construct(string $serverToken, int $timeout = 60)
  /**
  * Send an email.
  *
- * @param string $from The sender of the email. (Your account must have an associated Sender Signature for the address used.)
- * @param string $to the recipient of the email. Multiple recipients can be comma-separated (maximum 50 for to, cc, and bcc combined)
- * @param string $subject the subject of the email
- * @param null|string $htmlBody the HTML content of the message, optional if Text Body is specified
- * @param null|string $textBody the text content of the message, optional if HTML Body is specified
- * @param null|string $tag a tag associated with this message, useful for classifying sent messages
- * @param null|bool $trackOpens true if you want Postmark to track opens of HTML emails
- * @param null|string $replyTo reply to email address
- * @param null|string $cc Carbon Copy recipients, comma-separated
- * @param null|string $bcc blind Carbon Copy recipients, comma-separated
- * @param null|array $headers headers to be included with the sent email message
- * @param null|array $attachments an array of PostmarkAttachment objects
- * @param null|string $trackLinks can be any of "None", "HtmlAndText", "HtmlOnly", "TextOnly" to enable link tracking
- * @param null|array $metadata Add metadata to the message. The metadata is an associative array, and values will be evaluated as strings by Postmark.
- * @param null|string $messageStream The message stream used to send this message. If not provided, the default transactional stream "outbound" will be used.
+ * @param string  $from The sender of the email. (Your account must have an associated Sender Signature for the address used.)
+ * @param array|string $to the recipient of the email. Multiple recipients can be comma-separated or array (maximum 50 for to, cc, and bcc combined)
+ * @param string  $subject the subject of the email
+ * @param null|string  $htmlBody the HTML content of the message, optional if Text Body is specified
+ * @param null|string  $textBody the text content of the message, optional if HTML Body is specified
+ * @param null|string  $tag a tag associated with this message, useful for classifying sent messages
+ * @param null|bool  $trackOpens true if you want Postmark to track opens of HTML emails
+ * @param null|string  $replyTo reply to email address
+ * @param null|array|string $cc Carbon Copy recipients, comma-separated
+ * @param null|array|string $bcc blind Carbon Copy recipients, comma-separated
+ * @param null|array  $headers headers to be included with the sent email message
+ * @param null|array  $attachments an array of PostmarkAttachment objects
+ * @param null|string  $trackLinks can be any of "None", "HtmlAndText", "HtmlOnly", "TextOnly" to enable link tracking
+ * @param null|array  $metadata Add metadata to the message. The metadata is an associative array, and values will be evaluated as strings by Postmark.
+ * @param null|string  $messageStream The message stream used to send this message. If not provided, the default transactional stream "outbound" will be used.
  *
  * @throws PostmarkException
  */
  public function sendEmail(
  string $from,
- string $to,
+ array|string $to,
  string $subject,
  ?string $htmlBody = null,
  ?string $textBody = null,
  ?string $tag = null,
  ?bool $trackOpens = null,
  ?string $replyTo = null,
- ?string $cc = null,
- ?string $bcc = null,
+ null|array|string $cc = null,
+ null|array|string $bcc = null,
  ?array $headers = null,
  ?array $attachments = null,
  ?string $trackLinks = null,
@@ -99,9 +99,9 @@ public function sendEmail(
  ): PostmarkResponse {
  $body = [];
  $body['From'] = $from;
- $body['To'] = $to;
- $body['Cc'] = $cc;
- $body['Bcc'] = $bcc;
+ $body['To'] = $this->stringifyEmailAddress($to);
+ $body['Cc'] = $this->stringifyEmailAddress($cc);
+ $body['Bcc'] = $this->stringifyEmailAddress($bcc);
  $body['Subject'] = $subject;
  $body['HtmlBody'] = $htmlBody;
  $body['TextBody'] = $textBody;
@@ -211,35 +211,35 @@ public function sendEmailBatchWithTemplate(array $emailBatch = []): array
  /**
  * Send an email using a template.
  *
- * @param string $from The sender of the email. (Your account must have an associated Sender Signature for the address used.)
- * @param string $to the recipient of the email. Multiple recipients can be comma-separated (maximum 50 for to, cc, and bcc combined)
- * @param int|string $templateIdOrAlias the ID or alias of the template to use to generate the content of this message
- * @param array $templateModel the values to combine with the Templated content
- * @param bool $inlineCss if the template contains an HTMLBody, CSS is automatically inlined, you may opt-out of this by passing 'false' for this parameter
- * @param null|string $tag a tag associated with this message, useful for classifying sent messages
- * @param null|bool $trackOpens true if you want Postmark to track opens of HTML emails
- * @param null|string $replyTo reply to email address
- * @param null|string $cc Carbon Copy recipients, comma-separated
- * @param null|string $bcc blind Carbon Copy recipients, comma-separated
- * @param null|array $headers headers to be included with the sent email message
- * @param null|array $attachments an array of PostmarkAttachment objects
- * @param null|string $trackLinks can be any of "None", "HtmlAndText", "HtmlOnly", "TextOnly" to enable link tracking
- * @param null|array $metadata Add metadata to the message. The metadata is an associative array , and values will be evaluated as strings by Postmark.
- * @param null|string $messageStream The message stream used to send this message. If not provided, the default transactional stream "outbound" will be used.
+ * @param string  $from The sender of the email. (Your account must have an associated Sender Signature for the address used.)
+ * @param array|string $to the recipient of the email. Multiple recipients can be comma-separated or array (maximum 50 for to, cc, and bcc combined)
+ * @param int|string  $templateIdOrAlias the ID or alias of the template to use to generate the content of this message
+ * @param array  $templateModel the values to combine with the Templated content
+ * @param bool  $inlineCss if the template contains an HTMLBody, CSS is automatically inlined, you may opt-out of this by passing 'false' for this parameter
+ * @param null|string  $tag a tag associated with this message, useful for classifying sent messages
+ * @param null|bool  $trackOpens true if you want Postmark to track opens of HTML emails
+ * @param null|string  $replyTo reply to email address
+ * @param null|array|string $cc Carbon Copy recipients, comma-separated
+ * @param null|array|string $bcc blind Carbon Copy recipients, comma-separated
+ * @param null|array  $headers headers to be included with the sent email message
+ * @param null|array  $attachments an array of PostmarkAttachment objects
+ * @param null|string  $trackLinks can be any of "None", "HtmlAndText", "HtmlOnly", "TextOnly" to enable link tracking
+ * @param null|array  $metadata Add metadata to the message. The metadata is an associative array , and values will be evaluated as strings by Postmark.
+ * @param null|string  $messageStream The message stream used to send this message. If not provided, the default transactional stream "outbound" will be used.
  *
  * @throws PostmarkException
  */
  public function sendEmailWithTemplate(
  string $from,
- string $to,
+ array|string $to,
  int|string $templateIdOrAlias,
  array $templateModel,
  bool $inlineCss = true,
  ?string $tag = null,
  ?bool $trackOpens = null,
  ?string $replyTo = null,
- ?string $cc = null,
- ?string $bcc = null,
+ null|array|string $cc = null,
+ null|array|string $bcc = null,
  ?array $headers = null,
  ?array $attachments = null,
  ?string $trackLinks = null,
@@ -248,9 +248,9 @@ public function sendEmailWithTemplate(
  ): PostmarkResponse {
  $body = [];
  $body['From'] = $from;
- $body['To'] = $to;
- $body['Cc'] = $cc;
- $body['Bcc'] = $bcc;
+ $body['To'] = $this->stringifyEmailAddress($to);
+ $body['Cc'] = $this->stringifyEmailAddress($cc);
+ $body['Bcc'] = $this->stringifyEmailAddress($bcc);
  $body['Tag'] = $tag;
  $body['ReplyTo'] = $replyTo;
  $body['Headers'] = $this->fixHeaders($headers);
@@ -990,7 +990,7 @@ public function getOutboundEmailClientStatistics(
  *
  * @throws PostmarkException
  */
- public function getOutboundReadTimeStatistics(string $tag = null, string $fromdate = null, string $todate = null): DynamicResponseModel
+ public function getOutboundReadTimeStatistics(?string $tag = null, ?string $fromdate = null, ?string $todate = null): DynamicResponseModel
  {
  $query = [];
 
@@ -1588,6 +1588,23 @@ public function unarchiveMessageStream(string $id): PostmarkMessageStream
  return new PostmarkMessageStream((array) $this->processRestRequest('POST', "/message-streams/{$id}/unarchive"));
  }
 
+ /**
+ * The Postmark API requires a string for email addresses and limits the emails to a maximum of 50 across to, cc,
+ * and bcc addresses. This will throw an exception from the API if the limit is reached.
+ */
+ protected function stringifyEmailAddress(null|array|string $emailAddress): ?string
+ {
+ if (null === $emailAddress || is_string($emailAddress)) {
+ return $emailAddress;
+ }
+
+ if (is_array($emailAddress)) {
+ $emailAddress = implode(',', $emailAddress);
+ }
+
+ return $emailAddress;
+ }
+
  /**
  * The Postmark API wants an Array of Key-Value pairs, not a dictionary object,
  * therefore, we need to wrap the elements in an array.

testing_keys.json.example

@@ -1,6 +1,7 @@
 {
  "READ_INBOUND_TEST_SERVER_TOKEN" : "<token>",
  "READ_SELENIUM_TEST_SERVER_TOKEN" : "<token>",
+ "READ_SELENIUM_OPEN_TRACKING_TOKEN" : "<token>",
  "READ_LINK_TRACKING_TEST_SERVER_TOKEN" : "<token>",
 
  "WRITE_ACCOUNT_TOKEN" : "<token>",

tests/PostmarkClientEmailAsStringOrArrayTest.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace Postmark\Tests;
+
+use Postmark\PostmarkClient;
+
+require_once __DIR__ . '/PostmarkClientBaseTest.php';
+
+/**
+ * @internal
+ *
+ * @coversNothing
+ */
+class PostmarkClientEmailsAsStringOrArrayTest extends PostmarkClientBaseTest
+{
+ public function testCanSendArray(): void
+ {
+ $tk = parent::$testKeys;
+ $client = new PostmarkClient($tk->WRITE_TEST_SERVER_TOKEN, $tk->TEST_TIMEOUT);
+ $currentTime = date('c');
+ $emailsAsArray = [];
+ for ($i = 1; $i <= 50; ++$i) {
+ $emailsAsArray[] = str_replace('@', '+' . $i . '@', $tk->WRITE_TEST_EMAIL_RECIPIENT_ADDRESS);
+ }
+
+ $response = $client->sendEmail(
+ $tk->WRITE_TEST_SENDER_EMAIL_ADDRESS,
+ $emailsAsArray,
+ "Hello from the PHP Postmark Client Tests! ({$currentTime})",
+ '<b>Hi there!</b>',
+ 'This is a text body for a test email.',
+ );
+ $this->assertNotEmpty($response, 'The client could not send a basic message.');
+ }
+
+ public function testCanSendString(): void
+ {
+ $tk = parent::$testKeys;
+ $client = new PostmarkClient($tk->WRITE_TEST_SERVER_TOKEN, $tk->TEST_TIMEOUT);
+ $currentTime = date('c');
+ $emailsAsString = '';
+ for ($i = 1; $i <= 50; ++$i) {
+ $emailsAsString .= str_replace('@', '+' . $i . '@', $tk->WRITE_TEST_EMAIL_RECIPIENT_ADDRESS) . ',';
+ }
+
+ $response = $client->sendEmail(
+ $tk->WRITE_TEST_SENDER_EMAIL_ADDRESS,
+ $emailsAsString,
+ "Hello from the PHP Postmark Client Tests! ({$currentTime})",
+ '<b>Hi there!</b>',
+ 'This is a text body for a test email.',
+ );
+ $this->assertNotEmpty($response, 'The client could not send a basic message.');
+ }
+}