Add Sandbox and Domain names; deprecate the Inbox and SendingDomain names

README.md

@@ -77,7 +77,7 @@ Example `.env` variables (or export in shell):
 ```
 MAILTRAP_API_KEY=your_api_token # https://mailtrap.io/api-tokens
 MAILTRAP_USE_SANDBOX=true       # true/false toggle
-MAILTRAP_INBOX_ID=123456        # Only needed for sandbox
+MAILTRAP_SANDBOX_ID=123456      # Only needed for sandbox
 ```
 
 Bootstrap logic:
@@ -93,12 +93,12 @@ require __DIR__ . '/vendor/autoload.php';
 
 $apiKey    = getenv('MAILTRAP_API_KEY');
 $isSandbox = filter_var(getenv('MAILTRAP_USE_SANDBOX'), FILTER_VALIDATE_BOOL);
-$inboxId   = $isSandbox ? getenv('MAILTRAP_INBOX_ID') : null; // required only for sandbox
+$sandboxId = $isSandbox ? getenv('MAILTRAP_SANDBOX_ID') : null; // required only for sandbox
 
 $client = MailtrapClient::initSendingEmails(
     apiKey: $apiKey,
     isSandbox: $isSandbox,
-    inboxId: $inboxId // null is ignored for production
+    sandboxId: $sandboxId // null is ignored for production
 );
 
 $email = (new MailtrapEmail())
@@ -142,7 +142,7 @@ $mailtrap = MailtrapClient::initSendingEmails(
     apiKey: getenv('MAILTRAP_API_KEY'), # your API token
     isBulk: false,                      # set to true for bulk email sending (false by default)
     isSandbox: false,                   # set to true for sandbox mode       (false by default)
-    inboxId: null                       # optional, only for sandbox mode    (false by default)
+    sandboxId: null                     # required only for sandbox mode     (null by default)
 );
 
 $email = (new MailtrapEmail())
@@ -239,21 +239,21 @@ Email API:
 - Batch send (Bulk) – [`batch/bulk.php`](examples/batch/bulk.php)
 - Batch send with Template (Transactional) – [`batch/transactional_template.php`](examples/batch/transactional_template.php)
 - Batch send with Template (Bulk) – [`batch/bulk_template.php`](examples/batch/bulk_template.php)
-- Sending domain management CRUD – [`sending-domains/all.php`](examples/sending-domains/all.php)
-- Sending domain company info – [`sending-domains/company-info.php`](examples/sending-domains/company-info.php)
+- Domain management CRUD – [`domains/all.php`](examples/domains/all.php)
+- Domain company info – [`domains/company-info.php`](examples/domains/company-info.php)
 - Suppressions (create, find & delete) – [`sending/suppressions.php`](examples/sending/suppressions.php)
 - Tracking Opt-outs (list, create & delete) – [`sending/tracking-opt-outs.php`](examples/sending/tracking-opt-outs.php)
 - Email Logs (list & get by message ID) – [`sending/email-logs.php`](examples/sending/email-logs.php)
 
-Email Sandbox (Testing):
-- Send an email (Sandbox) – [`testing/send-mail.php`](examples/testing/send-mail.php)
-- Send an email with a Template (Sandbox) – [`testing/template.php`](examples/testing/template.php)
+Email Sandbox:
+- Send an email (Sandbox) – [`sandbox/send-mail.php`](examples/sandbox/send-mail.php)
+- Send an email with a Template (Sandbox) – [`sandbox/template.php`](examples/sandbox/template.php)
 - Batch send (Sandbox) – [`batch/sandbox.php`](examples/batch/sandbox.php)
 - Batch send with Template (Sandbox) – [`batch/sandbox_template.php`](examples/batch/sandbox_template.php)
-- Message management CRUD – [`testing/messages.php`](examples/testing/messages.php)
-- Inbox management CRUD – [`testing/inboxes.php`](examples/testing/inboxes.php)
-- Project management CRUD – [`testing/projects.php`](examples/testing/projects.php)
-- Attachments operations – [`testing/attachments.php`](examples/testing/attachments.php)
+- Message management CRUD – [`sandbox/messages.php`](examples/sandbox/messages.php)
+- Sandbox management CRUD – [`sandbox/sandboxes.php`](examples/sandbox/sandboxes.php)
+- Project management CRUD – [`sandbox/projects.php`](examples/sandbox/projects.php)
+- Attachments operations – [`sandbox/attachments.php`](examples/sandbox/attachments.php)
 
 Inbound Email API:
 - Folder management CRUD – [`inbound/folders.php`](examples/inbound/folders.php)
@@ -297,6 +297,31 @@ See the full indexed list at [`examples/README.md`](examples/README.md).
 Webhooks:
 - Verifying webhook signatures – [`webhooks/verify_signature.php`](examples/webhooks/verify_signature.php)
 
+## Renamed APIs
+
+The Email Sandbox's testing inboxes are now called **sandboxes**, and sending domains are now called **domains**.
+The SDK follows these names. The old ones still work: they call the same API endpoints, and each emits an
+`E_USER_DEPRECATED` notice the first time it is used. Symfony and Laravel log these notices; plain PHP ignores them.
+The old names will be removed in a future major release.
+
+| Old name (deprecated) | New name |
+|---|---|
+| `MailtrapSandboxClient::inboxes($accountId)` | `MailtrapSandboxClient::sandboxes($accountId)` |
+| `Mailtrap\Api\Sandbox\Inbox` | `Mailtrap\Api\Sandbox\Sandbox` |
+| `Inbox::getInboxAttributes($inboxId)` | `Sandbox::getSandboxAttributes($sandboxId)` |
+| `Mailtrap\DTO\Request\Inbox` | `Mailtrap\DTO\Request\Sandbox` |
+| `inboxId:` argument of `MailtrapClient::initSendingEmails()` and of the sandbox `emails()`, `messages()` and `attachments()` | `sandboxId:` |
+| `getInboxId()` of the sandbox `Emails`, `Message` and `Attachment` APIs | `getSandboxId()` |
+| Symfony DSN option `?inboxId=` | `?sandboxId=` |
+| Laravel `services.mailtrap-sdk.inboxId` config key | `services.mailtrap-sdk.sandboxId` (`MAILTRAP_SANDBOX_ID`) |
+| `Domain::getSendingDomains()` | `Domain::getDomains()` |
+| `Domain::createSendingDomain($domainName)` | `Domain::createDomain($domainName)` |
+| `Domain::updateSendingDomain($domainId, $domain)` | `Domain::updateDomain($domainId, $domain)` |
+| `Domain::deleteSendingDomain($domainId)` | `Domain::deleteDomain($domainId)` |
+
+Names that mirror an API field keep the old term, for example `inbox_id` in message responses,
+`User::getList($inboxIds)`, `PermissionInterface::TYPE_INBOX` and the `sendingDomainIds` stats filters.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on [GitHub](https://github.com/railsware/mailtrap-php). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).

UPGRADE-2.0.md

@@ -68,7 +68,7 @@ UPGRADE FROM 1.x to 2.0
   ```
 
 ### Sandbox API
-* **BC BREAK**: Rebuild `Projects` & `Messages` & `Attachments` & `Inboxes` layers ([examples](examples/testing))
+* **BC BREAK**: Rebuild `Projects` & `Messages` & `Attachments` & `Inboxes` layers ([examples](examples/sandbox))
 
   __Before__:
   ```php

examples/README.md

@@ -3,8 +3,8 @@
 Central index of runnable example scripts demonstrating Mailtrap PHP SDK features. Each script is intentionally minimal; open the file to inspect parameters. Run examples from project root (adjust env vars first).
 
 ## Prerequisites
-* Export or place inside the file your ENV variables (MAILTRAP_API_KEY, MAILTRAP_INBOX_ID, etc)
-* Some examples require a verified sending domain (production / bulk / templates).
+* Export or place inside the file your ENV variables (MAILTRAP_API_KEY, MAILTRAP_SANDBOX_ID, etc)
+* Some examples require a verified domain (production / bulk / templates).
 
 ## Contents
 
@@ -31,16 +31,16 @@ Central index of runnable example scripts demonstrating Mailtrap PHP SDK feature
 | Sandbox batch send | [`batch/sandbox.php`](batch/sandbox.php) |
 | Sandbox batch send (template) | [`batch/sandbox_template.php`](batch/sandbox_template.php) |
 
-### Sandbox (Email Testing)
+### Email Sandbox
 
 | Purpose | File |
 |---------|------|
-| Sandbox transactional send | [`testing/send-mail.php`](testing/send-mail.php) |
-| Sandbox send with template | [`testing/template.php`](testing/template.php) |
-| Manage attachments of a message | [`testing/attachments.php`](testing/attachments.php) |
-| Inbox CRUD / listing | [`testing/inboxes.php`](testing/inboxes.php) |
-| Message CRUD / listing | [`testing/messages.php`](testing/messages.php) |
-| Project CRUD / listing | [`testing/projects.php`](testing/projects.php) |
+| Sandbox transactional send | [`sandbox/send-mail.php`](sandbox/send-mail.php) |
+| Sandbox send with template | [`sandbox/template.php`](sandbox/template.php) |
+| Manage attachments of a message | [`sandbox/attachments.php`](sandbox/attachments.php) |
+| Sandbox CRUD / listing | [`sandbox/sandboxes.php`](sandbox/sandboxes.php) |
+| Message CRUD / listing | [`sandbox/messages.php`](sandbox/messages.php) |
+| Project CRUD / listing | [`sandbox/projects.php`](sandbox/projects.php) |
 
 ### Inbound Email
 
@@ -68,8 +68,8 @@ Central index of runnable example scripts demonstrating Mailtrap PHP SDK feature
 |---------|------|
 | Templates CRUD + paginated list (experimental) | [`templates/templates.php`](templates/templates.php) |
 | Email templates CRUD | [`templates/all.php`](templates/all.php) |
-| Sending domains CRUD | [`sending-domains/all.php`](sending-domains/all.php) |
-| Sending domain company info | [`sending-domains/company-info.php`](sending-domains/company-info.php) |
+| Domains CRUD | [`domains/all.php`](domains/all.php) |
+| Domain company info | [`domains/company-info.php`](domains/company-info.php) |
 
 ### General API
 
@@ -104,6 +104,6 @@ For batch examples, ensure the stream (bulk vs transactional vs sandbox) matches
 ## Tips
 - Keep secrets out of committed files; rely on environment variables.
 - Template examples require existing template UUIDs in your Mailtrap account.
-- Sandbox examples need `MAILTRAP_INBOX_ID`.
+- Sandbox examples need `MAILTRAP_SANDBOX_ID`.
 
 ---

examples/batch/bulk.php

@@ -16,7 +16,7 @@
  * Users of this endpoint should check the success and errors for each message in the response (the results are ordered the same as the original messages - requests).
  * Please note that the endpoint accepts up to 500 messages per API call, and up to 50 MB payload size, including attachments.
  *
- * For this example, you need to have ready-to-use sending domain or, a Demo domain that allows sending emails to your own account email.
+ * For this example, you need to have ready-to-use domain or, a Demo domain that allows sending emails to your own account email.
  * @see https://help.mailtrap.io/article/69-sending-domain-setup
  */
 try {

examples/batch/bulk_template.php

@@ -15,7 +15,7 @@
  * UUID of email template. Subject, text and html will be generated from template using optional template_variables.
  * Optional template variables that will be used to generate actual subject, text and html from email template
  *
- * For this example, you need to have ready-to-use sending domain or, a Demo domain that allows sending emails to your own account email.
+ * For this example, you need to have ready-to-use domain or, a Demo domain that allows sending emails to your own account email.
  * @see https://help.mailtrap.io/article/69-sending-domain-setup
  */
 try {

examples/batch/sandbox.php

@@ -19,7 +19,7 @@
     $mailtrap = MailtrapClient::initSendingEmails(
         apiKey: $_ENV['MAILTRAP_API_KEY'], #your API token from here https://mailtrap.io/api-tokens
         isSandbox: true, # Sandbox sending (@see https://help.mailtrap.io/article/109-getting-started-with-mailtrap-email-testing)
-        inboxId: $_ENV['MAILTRAP_INBOX_ID'] # required param for sandbox sending
+        sandboxId: $_ENV['MAILTRAP_SANDBOX_ID'] # required param for sandbox sending
     );
 
     $baseEmail = (new MailtrapEmail())

examples/batch/sandbox_template.php

@@ -19,7 +19,7 @@
     $mailtrap = MailtrapClient::initSendingEmails(
         apiKey: $_ENV['MAILTRAP_API_KEY'], #your API token from here https://mailtrap.io/api-tokens
         isSandbox: true, # Sandbox sending (@see https://help.mailtrap.io/article/109-getting-started-with-mailtrap-email-testing)
-        inboxId: $_ENV['MAILTRAP_INBOX_ID'] # required param for sandbox sending
+        sandboxId: $_ENV['MAILTRAP_SANDBOX_ID'] # required param for sandbox sending
     );
 
     $baseEmail = (new MailtrapEmail())

examples/batch/transactional.php

@@ -16,7 +16,7 @@
  * Users of this endpoint should check the success and errors for each message in the response (the results are ordered the same as the original messages - requests).
  * Please note that the endpoint accepts up to 500 messages per API call, and up to 50 MB payload size, including attachments.
  *
- * For this example, you need to have ready-to-use sending domain or, a Demo domain that allows sending emails to your own account email.
+ * For this example, you need to have ready-to-use domain or, a Demo domain that allows sending emails to your own account email.
  * @see https://help.mailtrap.io/article/69-sending-domain-setup
  */
 try {

examples/batch/transactional_template.php

@@ -15,7 +15,7 @@
  * UUID of email template. Subject, text and html will be generated from template using optional template_variables.
  * Optional template variables that will be used to generate actual subject, text and html from email template
  *
- * For this example, you need to have ready-to-use sending domain or, a Demo domain that allows sending emails to your own account email.
+ * For this example, you need to have ready-to-use domain or, a Demo domain that allows sending emails to your own account email.
  * @see https://help.mailtrap.io/article/69-sending-domain-setup
  */
 try {

examples/sending-domains/all.php → examples/domains/all.php

@@ -12,15 +12,15 @@
 $accountId = (int) $_ENV['MAILTRAP_ACCOUNT_ID'];
 $config = new Config($_ENV['MAILTRAP_API_KEY']); #your API token from here https://mailtrap.io/api-tokens
 
-$sendingDomains = (new MailtrapSendingClient($config))->domains($accountId); #required parameter is accountId
+$domains = (new MailtrapSendingClient($config))->domains($accountId); #required parameter is accountId
 
 /**
- * Get a list of sending domains.
+ * Get a list of domains.
  *
  * GET https://mailtrap.io/api/accounts/{account_id}/domains
  */
 try {
-    $response = $sendingDomains->getSendingDomains();
+    $response = $domains->getDomains();
 
     // print the response body (array)
     var_dump(ResponseHelper::toArray($response));
@@ -30,14 +30,14 @@
 
 
 /**
- * Create a new sending domain
+ * Create a new domain
  *
  * POST https://mailtrap.io/api/accounts/{account_id}/domains
  */
 try {
     $domainName = 'example.com';
 
-    $response = $sendingDomains->createSendingDomain($domainName);
+    $response = $domains->createDomain($domainName);
 
     // print the response body (array)
     var_dump(ResponseHelper::toArray($response));
@@ -47,14 +47,14 @@
 
 
 /**
- * Get a sending domain by ID
+ * Get a domain by ID
  *
  * GET https://mailtrap.io/api/accounts/{account_id}/domains/{domain_id}
  */
 try {
     $domainId = (int) $_ENV['MAILTRAP_DOMAIN_ID']; // Set this environment variable with a valid domain ID
 
-    $response = $sendingDomains->getDomainById($domainId);
+    $response = $domains->getDomainById($domainId);
 
     // print the response body (array)
     var_dump(ResponseHelper::toArray($response));
@@ -72,7 +72,7 @@
     $domainId = (int) $_ENV['MAILTRAP_DOMAIN_ID']; // Set this environment variable with a valid domain ID
     $email = 'devops@example.com'; // Email address to send setup instructions to
 
-    $response = $sendingDomains->sendDomainSetupInstructions($domainId, $email);
+    $response = $domains->sendDomainSetupInstructions($domainId, $email);
 
     // print the response body (array)
     var_dump(ResponseHelper::toArray($response));
@@ -82,14 +82,14 @@
 
 
 /**
- * Update sending domain configuration settings
+ * Update domain configuration settings
  *
  * PATCH https://mailtrap.io/api/accounts/{account_id}/domains/{domain_id}
  */
 try {
     $domainId = (int) $_ENV['MAILTRAP_DOMAIN_ID']; // Set this environment variable with a valid domain ID
 
-    $response = $sendingDomains->updateSendingDomain(
+    $response = $domains->updateDomain(
         $domainId,
         new UpdateDomain(
             openTrackingEnabled: true,
@@ -108,14 +108,14 @@
 
 
 /**
- * Delete a sending domain
+ * Delete a domain
  *
  * DELETE https://mailtrap.io/api/accounts/{account_id}/domains/{domain_id}
  */
 try {
     $domainId = (int) $_ENV['MAILTRAP_DOMAIN_ID']; // Set this environment variable with a valid domain ID
 
-    $response = $sendingDomains->deleteSendingDomain($domainId);
+    $response = $domains->deleteDomain($domainId);
 
     // Print the response status code
     var_dump($response->getStatusCode());

examples/sending-domains/company-info.php → examples/domains/company-info.php

@@ -17,7 +17,7 @@
 $companyInfo = (new MailtrapSendingClient($config))->companyInfo($domainId); #required parameter is domainId
 
 /**
- * Create company info for a sending domain
+ * Create company info for a domain
  *
  * POST https://mailtrap.io/api/domains/{domain_id}/company_info
  */
@@ -45,7 +45,7 @@
 
 
 /**
- * Get company info for a sending domain
+ * Get company info for a domain
  *
  * GET https://mailtrap.io/api/domains/{domain_id}/company_info
  */
@@ -60,7 +60,7 @@
 
 
 /**
- * Update company info for a sending domain
+ * Update company info for a domain
  *
  * PATCH https://mailtrap.io/api/domains/{domain_id}/company_info
  *

examples/email-campaigns/all.php

@@ -42,7 +42,7 @@
 try {
     $response = $emailCampaigns->createEmailCampaign(new CreateEmailCampaign(
         name: 'Spring Sale',
-        domainId: (int) $_ENV['MAILTRAP_DOMAIN_ID'], // set this environment variable with your sending domain ID
+        domainId: (int) $_ENV['MAILTRAP_DOMAIN_ID'], // set this environment variable with your domain ID
         fromLocalPart: 'news',
         templateAttributes: new TemplateAttributes(subject: 'Spring is here — 30% off'),
         fromDisplayName: 'Acme Marketing',

examples/general/billing.php

@@ -12,7 +12,7 @@
 
 
 /**
- * Get current billing cycle usage for Email Testing and Email Sending.
+ * Get current billing cycle usage for Email Sandbox and Email Sending.
  *
  * GET https://mailtrap.io/api/accounts/{account_id}/billing/usage
  */

examples/laravel/sandbox.php

@@ -19,7 +19,7 @@
     $response = MailtrapClient::initSendingEmails(
         apiKey:    $_ENV['MAILTRAP_API_KEY'], // your API token from here https://mailtrap.io/api-tokens
         isSandbox: true,
-        inboxId:   $_ENV['MAILTRAP_INBOX_ID'], // your Inbox ID from here https://mailtrap.io/inboxes
+        sandboxId: $_ENV['MAILTRAP_SANDBOX_ID'], // your Sandbox ID from here https://mailtrap.io/inboxes
     )->send($email);
 
     var_dump(ResponseHelper::toArray($response));

examples/marketing-stats/all.php

@@ -38,7 +38,7 @@
 
 /**
  * Get Email Marketing stats with filters: campaigns only, sent to Google and Yahoo.
- * Pass `sendingDomainIds` as well to narrow the stats to specific sending domains.
+ * Pass `sendingDomainIds` as well to narrow the stats to specific domains.
  *
  * GET https://mailtrap.io/api/marketing/stats
  */

examples/testing/attachments.php → examples/sandbox/attachments.php

@@ -7,10 +7,10 @@
 require __DIR__ . '/../../vendor/autoload.php';
 
 $accountId = $_ENV['MAILTRAP_ACCOUNT_ID'];
-$inboxId = $_ENV['MAILTRAP_INBOX_ID'];
+$sandboxId = $_ENV['MAILTRAP_SANDBOX_ID'];
 $config = new Config($_ENV['MAILTRAP_API_KEY']); #your API token from here https://mailtrap.io/api-tokens
 
-$sandboxAttachments = (new MailtrapSandboxClient($config))->attachments($accountId, $inboxId); #required parameters are accountId amd inboxId
+$sandboxAttachments = (new MailtrapSandboxClient($config))->attachments($accountId, $sandboxId); #required parameters are accountId and sandboxId
 
 
 /**