normalizeEmail($email); $normalizedFirstName = $this->normalizeName($firstName); $normalizedLastName = $this->normalizeName($lastName); if (null === $normalizedFirstName && null === $normalizedLastName) { return; } $contactData = $this->buildContactDataPayload($normalizedFirstName, $normalizedLastName); if ([] === $contactData) { return; } $contactId = $this->findOrCreateContactId($normalizedEmail); $this->request('POST', 'contactdata', [ 'json' => [ 'ContactID' => $contactId, 'Data' => $contactData, ], ]); } public function isSubscribed(string $email, ?int $listId = null): bool { $resolvedListId = $this->resolveListId($listId); $normalizedEmail = $this->normalizeEmail($email); $contactId = $this->resolveContactId($normalizedEmail); if (null === $contactId) { return false; } $response = $this->request('GET', 'Listrecipient', [ 'query' => [ 'Contact' => $contactId, 'ContactsList' => $resolvedListId, ], ]); $entries = $response['Data'] ?? []; if (false === is_array($entries)) { return false; } foreach ($entries as $entry) { if (false === is_array($entry)) { continue; } $entryContactId = isset($entry['ContactID']) ? (int) $entry['ContactID'] : null; if ($entryContactId !== $contactId) { continue; } $isActive = true === ($entry['IsActive'] ?? false); $isUnsubscribed = true === ($entry['IsUnsubscribed'] ?? false); return $isActive && !$isUnsubscribed; } return false; } public function ensureSubscribed(string $email, ?int $listId = null): void { $resolvedListId = $this->resolveListId($listId); $normalizedEmail = $this->normalizeEmail($email); $resource = sprintf('Contactslist/%s/managecontact', $resolvedListId); try { $this->request('POST', $resource, [ 'json' => [ 'Email' => $normalizedEmail, 'Action' => 'addforce', ], ]); } catch (NewsletterProviderException $exception) { $this->logger->error('Mailjet subscribe failed', [ 'email' => $normalizedEmail, 'list_id' => $resolvedListId, 'error' => $exception->getMessage(), ]); throw $exception; } } /** * @return array */ public function createEventCallbackUrl(string $eventType, string $url, int $version = 2, bool $isBackup = false): array { return $this->request('POST', 'eventcallbackurl', [ 'json' => [ 'EventType' => strtolower(trim($eventType)), 'Url' => $url, 'Version' => $version, 'isBackup' => $isBackup, ], ]); } public function deleteEventCallbackUrl(int $eventCallbackUrlId): void { $this->request('DELETE', sprintf('eventcallbackurl/%d', $eventCallbackUrlId), [ 'allow_empty' => true, ]); } public function createContactsList(string $name): int { $this->assertConfigured(); $response = $this->request('POST', 'contactslist', [ 'json' => [ 'Name' => $name, ], ]); $listId = $response['Data'][0]['ID'] ?? null; if (null === $listId) { throw new NewsletterProviderException(sprintf('Mailjet did not return an id for the new contact list %s', $name)); } return (int) $listId; } /** * Adds the contacts as subscribed, including any who unsubscribed from this list before. * Mailjet processes the request as an asynchronous job. * * @param list $contacts * * @return int|null the job id */ public function addContactsToList(int $listId, array $contacts): ?int { $this->assertConfigured(); $payload = []; foreach ($contacts as $contact) { $entry = ['Email' => $this->normalizeEmail($contact['email'])]; $firstName = $this->normalizeName($contact['firstName']); if (null !== $firstName && true === isset($this->contactMetadataFields['firstName'])) { $entry['Properties'] = [$this->contactMetadataFields['firstName'] => $firstName]; } $payload[] = $entry; } $response = $this->request('POST', sprintf('contactslist/%d/managemanycontacts', $listId), [ 'json' => [ 'Action' => 'addforce', 'Contacts' => $payload, ], ]); $jobId = $response['Data'][0]['JobID'] ?? null; return null !== $jobId ? (int) $jobId : null; } /** * @return list */ public function getListContactIds(int $listId): array { $this->assertConfigured(); $contactIds = []; $offset = 0; do { $response = $this->request('GET', 'listrecipient', [ 'query' => [ 'ContactsList' => $listId, 'Limit' => self::PAGE_LIMIT, 'Offset' => $offset, ], ]); $entries = true === is_array($response['Data'] ?? null) ? $response['Data'] : []; foreach ($entries as $entry) { if (true === is_array($entry) && true === isset($entry['ContactID'])) { $contactIds[] = (int) $entry['ContactID']; } } $offset += self::PAGE_LIMIT; } while (self::PAGE_LIMIT === count($entries)); return array_values(array_unique($contactIds)); } /** * Lists the contact is on, subscribed or not. Mailjet includes lists deleted within the last 60 days. * * @return list */ public function getContactListIds(int $contactId): array { $this->assertConfigured(); $response = $this->request('GET', sprintf('contact/%d/getcontactslists', $contactId), [ 'allow_404' => true, ]); $listIds = []; foreach ($response['Data'] ?? [] as $entry) { if (true === is_array($entry) && true === isset($entry['ListID'])) { $listIds[] = (int) $entry['ListID']; } } return $listIds; } public function deleteContactsList(int $listId): void { $this->assertConfigured(); $this->request('DELETE', sprintf('contactslist/%d', $listId), [ 'allow_404' => true, 'allow_empty' => true, ]); } /** * GDPR deletion: Mailjet anonymises the contact immediately and purges it after 30 days. * This cannot be undone. */ public function deleteContact(int $contactId): void { $this->assertConfigured(); $this->request('DELETE', sprintf('contacts/%d', $contactId), [ 'allow_404' => true, 'allow_empty' => true, 'api_version' => 'v4', ]); } private function findOrCreateContactId(string $email): int { $contactId = $this->resolveContactId($email); if (null !== $contactId) { return $contactId; } try { $contactId = $this->createContact($email); if (null !== $contactId) { return $contactId; } } catch (NewsletterProviderException $exception) { $contactId = $this->resolveContactId($email); if (null !== $contactId) { return $contactId; } throw $exception; } $contactId = $this->resolveContactId($email); if (null !== $contactId) { return $contactId; } throw new NewsletterProviderException(sprintf('Mailjet contact could not be resolved for %s', $email)); } private function createContact(string $email): ?int { $response = $this->request('POST', 'Contact', [ 'json' => [ 'Email' => $email, ], ]); return $this->extractContactId($response); } private function resolveContactId(string $email): ?int { $this->assertConfigured(); $response = $this->request('GET', 'Contact', [ 'query' => [ 'Email' => $email, 'Limit' => 1, ], 'allow_404' => true, ]); return $this->extractContactId($response); } /** * @param array $response */ private function extractContactId(array $response): ?int { $entry = $response['Data'][0] ?? null; if (true === is_array($entry) && true === isset($entry['ID'])) { return (int) $entry['ID']; } if (true === isset($response['Data']['ID'])) { return (int) $response['Data']['ID']; } return null; } /** * @return list */ private function buildContactDataPayload(?string $firstName, ?string $lastName): array { $data = []; if (null !== $firstName && true === isset($this->contactMetadataFields['firstName'])) { $data[] = [ 'Name' => $this->contactMetadataFields['firstName'], 'Value' => $firstName, ]; } if (null !== $lastName && true === isset($this->contactMetadataFields['lastName'])) { $data[] = [ 'Name' => $this->contactMetadataFields['lastName'], 'Value' => $lastName, ]; } return $data; } /** * @param array $options * * @return array */ private function request(string $method, string $resource, array $options = []): array { $allow404 = true === ($options['allow_404'] ?? false); $allowEmpty = true === ($options['allow_empty'] ?? false); $baseUrl = 'v4' === ($options['api_version'] ?? null) ? $this->getV4BaseUrl() : $this->getBaseUrl(); unset($options['allow_404']); unset($options['allow_empty']); unset($options['api_version']); $resourcePath = trim($resource, '/'); try { $response = $this->httpClient->request( $method, sprintf('%s/%s', $baseUrl, $resourcePath), array_merge($options, [ 'auth_basic' => sprintf('%s:%s', $this->apiKey, $this->apiSecret), ]) ); $statusCode = $response->getStatusCode(); if (404 === $statusCode && $allow404) { return []; } $content = $response->getContent(false); if ('' === trim($content)) { if (true === $allowEmpty && $statusCode < 400) { return []; } throw new NewsletterProviderException(sprintf('Mailjet request returned an empty response for resource %s', $resource)); } try { $payload = json_decode($content, true, 512, JSON_THROW_ON_ERROR); } catch (\JsonException $exception) { throw new NewsletterProviderException(sprintf('Mailjet request error for resource %s', $resource), previous: $exception); } if ($statusCode >= 400) { $payloadSummary = json_encode($payload, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE); $payloadSummary = false === $payloadSummary ? null : $payloadSummary; throw new NewsletterProviderException(sprintf('Mailjet request failed with status %d for resource %s%s', $statusCode, $resource, null !== $payloadSummary ? sprintf(' (%s)', $payloadSummary) : '')); } return $payload; } catch (\Throwable $exception) { if (true === $allow404 && true === str_contains($exception->getMessage(), '404')) { return []; } if ($exception instanceof NewsletterProviderException) { throw $exception; } throw new NewsletterProviderException(sprintf('Mailjet request error for resource %s', $resource), previous: $exception); } } private function getBaseUrl(): string { $baseUrl = null !== $this->apiBaseUrl && '' !== trim($this->apiBaseUrl) ? trim($this->apiBaseUrl) : self::DEFAULT_BASE_URL; return rtrim($baseUrl, '/'); } /** * The configured base URL points at v3 (`…/v3/REST`); the v4 API sits beside it on the same host. */ private function getV4BaseUrl(): string { $baseUrl = preg_replace('~/v3/REST$~i', '', $this->getBaseUrl()); return sprintf('%s/v4', $baseUrl); } private function assertConfigured(): void { if (true === empty($this->apiKey) || true === empty($this->apiSecret)) { throw new NewsletterProviderException('Mailjet newsletter service is not fully configured.'); } } private function resolveListId(?int $listId): string { $this->assertConfigured(); $resolvedListId = null !== $listId ? (string) $listId : (string) $this->defaultListId; if ('' === trim($resolvedListId)) { throw new NewsletterProviderException('Mailjet newsletter list is not configured.'); } return trim($resolvedListId); } private function normalizeEmail(string $email): string { return mb_strtolower(trim($email)); } private function normalizeName(?string $name): ?string { if (null === $name) { return null; } $trimmed = trim($name); if ('' === $trimmed) { return null; } return mb_substr($trimmed, 0, self::NAME_MAX_LENGTH); } }