Skip to content

Commit b48e1d1

Browse files
gaalferovgaalferov
authored
Merge pull request #38 from railsware/feature/contacts
Add Contact API functionality
2 parents a17c7bc + 747a7df commit b48e1d1

File tree

9 files changed

+641
-2
lines changed

9 files changed

+641
-2
lines changed

‎CHANGELOG.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
## [3.1.0] - 2025-05-27
2+
- Add Contacts API functionality
3+
14
## [3.0.0] - 2025-05-15
25

36
- [BC BREAK] Change Symfony&Laravel integration naming from `mailtrap+api` to `mailtrap+sdk` ([reason](https://symfony.com/packages/MailtrapMailer))

‎examples/general/contacts.php

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
<?php
2+
3+
use Mailtrap\Config;
4+
use Mailtrap\DTO\Request\Contact\CreateContact;
5+
use Mailtrap\DTO\Request\Contact\UpdateContact;
6+
use Mailtrap\Helper\ResponseHelper;
7+
use Mailtrap\MailtrapGeneralClient;
8+
9+
require __DIR__ . '/../vendor/autoload.php';
10+
11+
$accountId = getenv('MAILTRAP_ACCOUNT_ID');
12+
$config = new Config(getenv('MAILTRAP_API_KEY')); #your API token from here https://mailtrap.io/api-tokens
13+
$contacts = (new MailtrapGeneralClient($config))->contacts($accountId);
14+
15+
/**
16+
* Get all Contact Lists.
17+
*
18+
* GET https://mailtrap.io/api/accounts/{account_id}/contacts/lists
19+
*/
20+
try {
21+
$response = $contacts->getAllContactLists();
22+
23+
// print the response body (array)
24+
var_dump(ResponseHelper::toArray($response));
25+
} catch (Exception $e) {
26+
echo 'Caught exception: ', $e->getMessage(), PHP_EOL;
27+
}
28+
29+
30+
/**
31+
* Create a new Contact
32+
*
33+
* POST https://mailtrap.io/api/accounts/{account_id}/contacts
34+
*/
35+
try {
36+
$response = $contacts->createContact(
37+
CreateContact::init(
38+
'john.smith@example.com',
39+
['first_name' => 'John', 'last_name' => 'Smith'], // Fields
40+
[1, 2] // List IDs to which the contact will be added
41+
)
42+
);
43+
44+
// print the response body (array)
45+
var_dump(ResponseHelper::toArray($response));
46+
} catch (Exception $e) {
47+
echo 'Caught exception: ', $e->getMessage(), PHP_EOL;
48+
}
49+
50+
51+
/**
52+
* Update contact by ID or Email.
53+
*
54+
* PATCH https://mailtrap.io/api/accounts/{account_id}/contacts/{id_or_email}
55+
*/
56+
try {
57+
// Update contact by ID
58+
$response = $contacts->updateContactById(
59+
'019706a8-0000-0000-0000-4f26816b467a',
60+
UpdateContact::init(
61+
'john.smith@example.com',
62+
['first_name' => 'John', 'last_name' => 'Smith'], // Fields
63+
[3], // List IDs to which the contact will be added
64+
[1, 2], // List IDs from which the contact will be removed
65+
true // Unsubscribe the contact
66+
)
67+
);
68+
69+
// OR update contact by email
70+
$response = $contacts->updateContactByEmail(
71+
'john.smith@example.com',
72+
UpdateContact::init(
73+
'john.smith@example.com',
74+
['first_name' => 'John', 'last_name' => 'Smith'], // Fields
75+
[3], // List IDs to which the contact will be added
76+
[1, 2], // List IDs from which the contact will be removed
77+
true // Unsubscribe the contact
78+
)
79+
);
80+
81+
// print the response body (array)
82+
var_dump(ResponseHelper::toArray($response));
83+
} catch (Exception $e) {
84+
echo 'Caught exception: ', $e->getMessage(), PHP_EOL;
85+
}
86+
87+
88+
/**
89+
* Delete contact
90+
*
91+
* Delete https://mailtrap.io/api/accounts/{account_id}/contacts/{id_or_email}
92+
*/
93+
try {
94+
// Delete contact by ID
95+
$response = $contacts->deleteContactById('019706a8-0000-0000-0000-4f26816b467a');
96+
97+
// OR delete contact by email
98+
$response = $contacts->deleteContactByEmail('john.smith@example.com');
99+
100+
// print the response body (array)
101+
var_dump(ResponseHelper::toArray($response));
102+
} catch (Exception $e) {
103+
echo 'Caught exception: ', $e->getMessage(), PHP_EOL;
104+
}

‎src/Api/General/Contact.php

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Mailtrap\Api\General;
6+
7+
use Mailtrap\Api\AbstractApi;
8+
use Mailtrap\ConfigInterface;
9+
use Mailtrap\DTO\Request\Contact\CreateContact;
10+
use Mailtrap\DTO\Request\Contact\UpdateContact;
11+
use Psr\Http\Message\ResponseInterface;
12+
13+
/**
14+
* Class Contact
15+
*/
16+
class Contact extends AbstractApi implements GeneralInterface
17+
{
18+
public function __construct(ConfigInterface $config, private int $accountId)
19+
{
20+
parent::__construct($config);
21+
}
22+
23+
/**
24+
* Get all Contact Lists.
25+
*
26+
* @return ResponseInterface
27+
*/
28+
public function getAllContactLists(): ResponseInterface
29+
{
30+
return $this->handleResponse(
31+
$this->httpGet($this->getBasePath() . '/lists')
32+
);
33+
}
34+
35+
/**
36+
* Create a new Contact.
37+
*
38+
* @param CreateContact $contact
39+
* @return ResponseInterface
40+
*/
41+
public function createContact(CreateContact $contact): ResponseInterface
42+
{
43+
return $this->handleResponse(
44+
$this->httpPost(path: $this->getBasePath(), body: ['contact' => $contact->toArray()])
45+
);
46+
}
47+
48+
/**
49+
* Update an existing Contact by ID (UUID).
50+
*
51+
* @param string $contactId
52+
* @param UpdateContact $contact
53+
* @return ResponseInterface
54+
*/
55+
public function updateContactById(string $contactId, UpdateContact $contact): ResponseInterface
56+
{
57+
return $this->updateContact($contactId, $contact);
58+
}
59+
60+
/**
61+
* Update an existing Contact by Email.
62+
*
63+
* @param string $email
64+
* @param UpdateContact $contact
65+
* @return ResponseInterface
66+
*/
67+
public function updateContactByEmail(string $email, UpdateContact $contact): ResponseInterface
68+
{
69+
return $this->updateContact($email, $contact);
70+
}
71+
72+
/**
73+
* Delete a Contact by ID (UUID).
74+
*
75+
* @param string $contactId
76+
* @return ResponseInterface
77+
*/
78+
public function deleteContactById(string $contactId): ResponseInterface
79+
{
80+
return $this->deleteContact($contactId);
81+
}
82+
83+
/**
84+
* Delete a Contact by Email.
85+
*
86+
* @param string $email
87+
* @return ResponseInterface
88+
*/
89+
public function deleteContactByEmail(string $email): ResponseInterface
90+
{
91+
return $this->deleteContact($email);
92+
}
93+
94+
public function getAccountId(): int
95+
{
96+
return $this->accountId;
97+
}
98+
99+
/**
100+
* Update an existing Contact.
101+
*
102+
* @param string $contactIdOrEmail
103+
* @param UpdateContact $contact
104+
* @return ResponseInterface
105+
*/
106+
private function updateContact(string $contactIdOrEmail, UpdateContact $contact): ResponseInterface
107+
{
108+
return $this->handleResponse(
109+
$this->httpPut(
110+
path: $this->getBasePath() . '/' . urlencode($contactIdOrEmail),
111+
body: ['contact' => $contact->toArray()]
112+
)
113+
);
114+
}
115+
116+
/**
117+
* Delete a Contact by ID or Email.
118+
*
119+
* @param string $idOrEmail
120+
* @return ResponseInterface
121+
*/
122+
private function deleteContact(string $idOrEmail): ResponseInterface
123+
{
124+
return $this->handleResponse(
125+
$this->httpDelete($this->getBasePath() . '/' . urlencode($idOrEmail))
126+
);
127+
}
128+
129+
private function getBasePath(): string
130+
{
131+
return sprintf('%s/api/accounts/%s/contacts', $this->getHost(), $this->getAccountId());
132+
}
133+
}

‎src/DTO/Request/Contact/ContactInterface.php

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<?php
2+
3+
namespace Mailtrap\DTO\Request\Contact;
4+
5+
use Mailtrap\DTO\Request\RequestInterface;
6+
7+
interface ContactInterface extends RequestInterface
8+
{
9+
/**
10+
* The email of the contact.
11+
*
12+
* @return string
13+
*/
14+
public function getEmail(): string;
15+
16+
/**
17+
* The fields of the contact.
18+
*
19+
* @return array
20+
*/
21+
public function getFields(): array;
22+
}

‎src/DTO/Request/Contact/CreateContact.php

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Mailtrap\DTO\Request\Contact;
6+
7+
/**
8+
* Class CreateContact
9+
*/
10+
final class CreateContact implements ContactInterface
11+
{
12+
public function __construct(
13+
private string $email,
14+
private array $fields = [],
15+
private array $listIds = []
16+
) {
17+
}
18+
19+
public static function init(string $email, array $fields = [], array $listIds = []): self
20+
{
21+
return new self($email, $fields, $listIds);
22+
}
23+
24+
public function getEmail(): string
25+
{
26+
return $this->email;
27+
}
28+
29+
public function getFields(): array
30+
{
31+
return $this->fields;
32+
}
33+
34+
public function getListIds(): array
35+
{
36+
return $this->listIds;
37+
}
38+
39+
public function toArray(): array
40+
{
41+
return [
42+
'email' => $this->getEmail(),
43+
'fields' => $this->getFields(),
44+
'list_ids' => $this->getListIds(),
45+
];
46+
}
47+
}

‎src/DTO/Request/Contact/UpdateContact.php

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Mailtrap\DTO\Request\Contact;
6+
7+
/**
8+
* Class UpdateContact
9+
*/
10+
final class UpdateContact implements ContactInterface
11+
{
12+
public function __construct(
13+
private string $email,
14+
private array $fields = [],
15+
private array $listIdsIncluded = [],
16+
private array $listIdsExcluded = [],
17+
private ?bool $unsubscribed = null
18+
) {
19+
}
20+
21+
public static function init(
22+
string $email,
23+
array $fields = [],
24+
array $listIdsIncluded = [],
25+
array $listIdsExcluded = [],
26+
?bool $unsubscribed = null
27+
): self {
28+
return new self($email, $fields, $listIdsIncluded, $listIdsExcluded, $unsubscribed);
29+
}
30+
31+
public function getEmail(): string
32+
{
33+
return $this->email;
34+
}
35+
36+
public function getFields(): array
37+
{
38+
return $this->fields;
39+
}
40+
41+
public function getListIdsIncluded(): array
42+
{
43+
return $this->listIdsIncluded;
44+
}
45+
46+
public function getListIdsExcluded(): array
47+
{
48+
return $this->listIdsExcluded;
49+
}
50+
51+
public function getUnsubscribed(): ?bool
52+
{
53+
return $this->unsubscribed;
54+
}
55+
56+
public function toArray(): array
57+
{
58+
return array_filter(
59+
[
60+
'email' => $this->getEmail(),
61+
'fields' => $this->getFields(),
62+
'list_ids_included' => $this->getListIdsIncluded(),
63+
'list_ids_excluded' => $this->getListIdsExcluded(),
64+
'unsubscribed' => $this->getUnsubscribed(),
65+
],
66+
fn($value) => $value !== null
67+
);
68+
}
69+
}

0 commit comments

Comments
 (0)