Mailtrap PHP Client

https://github.com/mailtrap/mailtrap-php
Admin
An official PHP SDK and API client for Mailtrap.io, enabling developers to send transactional and...
Tokens:77,826
Snippets:493
Trust Score:8.2
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run example from project root

Source: https://github.com/mailtrap/mailtrap-php/blob/main/examples/README.md

Run any example script from the project root. Adjust environment variables first.

```bash
php examples/sending/minimal.php
```

--------------------------------

### Install with Symfony HTTP client

Source: https://github.com/mailtrap/mailtrap-php/blob/main/README.md

Use this command to install the Mailtrap PHP client with the recommended Symfony HTTP client and Nyholm PSR-7. This is the quickest way to get started.

```bash
composer require railsware/mailtrap-php symfony/http-client nyholm/psr7
```

--------------------------------

### Install Mailtrap SDK and dependencies

Source: https://github.com/mailtrap/mailtrap-php/blob/main/src/Bridge/Symfony/README.md

Run this Composer command to install the Mailtrap PHP SDK along with required Symfony packages for HTTP client, PSR-7, and Mailer.

```bash
composer require railsware/mailtrap-php symfony/http-client nyholm/psr7 symfony/mailer
```

--------------------------------

### Install with Guzzle HTTP client

Source: https://github.com/mailtrap/mailtrap-php/blob/main/README.md

Use this command to install the Mailtrap PHP client with the Guzzle HTTP client and the Guzzle 7 adapter. Choose this if you prefer Guzzle over Symfony.

```bash
composer require railsware/mailtrap-php guzzlehttp/guzzle php-http/guzzle7-adapter
```

--------------------------------

### Symfony Mailer DSN examples

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/configuration.md

Four DSN examples for the Mailtrap SDK transport. The scheme must be mailtrap+sdk, user is the API key, host defaults to send.api.mailtrap.io, and sandbox requires the inboxId query option.

```text
MAILER_DSN=mailtrap+sdk://API_KEY@default
MAILER_DSN=mailtrap+sdk://API_KEY@send.api.mailtrap.io
MAILER_DSN=mailtrap+sdk://API_KEY@bulk.api.mailtrap.io
MAILER_DSN=mailtrap+sdk://API_KEY@sandbox.api.mailtrap.io?inboxId=1000001
```

--------------------------------

### POST /api/accounts/{accountId}/sending_domains/{domainId}/send_setup_instructions

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sending-api.md

Emails the domain setup instructions to the specified email address.

```APIDOC
## POST /api/accounts/{accountId}/sending_domains/{domainId}/send_setup_instructions

### Description
Emails the domain setup instructions to the specified email address.

### Method
POST

### Endpoint
/api/accounts/{accountId}/sending_domains/{domainId}/send_setup_instructions

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The account ID.
- **domainId** (integer) - Required - The domain ID.

#### Request Body
- **email** (string) - Required - The email address to send instructions to.

### Request Example
{
  "email": "user@example.com"
}

### Response
#### Success Response (200)
- Returns a success message.

#### Response Example
(No example provided in source)
```

--------------------------------

### Create and list webhooks example

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/webhooks-api.md

Shows how to create a webhook, extract its ID and signing secret, update it, and list all webhooks. The signing secret is kept for signature verification.

```php
use Mailtrap\DTO\Request\Webhook\CreateWebhook;
use Mailtrap\DTO\Request\Webhook\UpdateWebhook;
use Mailtrap\DTO\Request\Webhook\Webhook;
use Mailtrap\Helper\ResponseHelper;
use Mailtrap\MailtrapClient;

$webhooks = (new MailtrapClient(new Config(getenv('MAILTRAP_API_KEY'))))
    ->sending()->webhooks($accountId);

$created = ResponseHelper::toArray($webhooks->createWebhook(
    new CreateWebhook(
        url: 'https://app.example.com/hooks/mailtrap',
        webhookType: Webhook::TYPE_EMAIL_SENDING,
        eventTypes: [Webhook::EVENT_DELIVERY, Webhook::EVENT_BOUNCE, Webhook::EVENT_OPEN],
        payloadFormat: Webhook::PAYLOAD_FORMAT_JSON,
        sendingStream: Webhook::SENDING_STREAM_TRANSACTIONAL,
        active: true,
    )
));
$webhookId = $created['id'];
$signingSecret = $created['signing_secret'];   // keep for WebhookSignature::verify()

$webhooks->updateWebhook($webhookId, new UpdateWebhook(
    active: false,
    eventTypes: [Webhook::EVENT_DELIVERY],     // replaces the full list server-side
));
var_dump(ResponseHelper::toArray($webhooks->getWebhooks()));
```

--------------------------------

### Sandbox Project and Inbox Setup

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sandbox-api.md

Demonstrates creating a sandbox project and inbox, updating the inbox, cleaning it, and listing inboxes using the Mailtrap PHP SDK.

```APIDOC
## Sandbox Project and Inbox Setup

### Description
Creates a sandbox project and inbox, updates the inbox name and email username, cleans the inbox, and retrieves the list of inboxes.

### Method
N/A (SDK method calls)

### Endpoint
N/A (SDK methods)

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The account ID for the sandbox.
- **projectId** (integer) - Required - The project ID for the inbox.
- **inboxId** (integer) - Required - The inbox ID to update or clean.

#### Request Body
- **name** (string) - Optional - The name of the project or inbox.
- **emailUsername** (string) - Optional - The email username for the inbox.

### Request Example
```php
use Mailtrap\DTO\Request\Inbox as InboxRequest;
use Mailtrap\Helper\ResponseHelper;
use Mailtrap\MailtrapClient;

$sandbox = (new MailtrapClient(new Config(getenv('MAILTRAP_API_KEY'))))->sandbox();
$projects = $sandbox->projects($accountId);
$inboxes  = $sandbox->inboxes($accountId);

$project = ResponseHelper::toArray($projects->create('My test project'));
$projectId = $project['project']['id'];

$inbox = ResponseHelper::toArray($inboxes->create($projectId, 'Main inbox'));
$inboxId = $inbox['inbox']['id'];

$inboxes->update($inboxId, new InboxRequest(name: 'Renamed', emailUsername: 'dev'));
$inboxes->clean($inboxId);
var_dump(ResponseHelper::toArray($inboxes->getList()));
```

### Response
#### Success Response (200)
- **project** (object) - The created project object.
- **inbox** (object) - The created inbox object.
- **list** (array) - The list of inboxes after operations.

#### Response Example
```json
{
  "project": {
    "id": 123,
    "name": "My test project"
  },
  "inbox": {
    "id": 456,
    "name": "Main inbox",
    "email_username": "dev"
  },
  "list": [
    {
      "id": 456,
      "name": "Renamed",
      "email_username": "dev"
    }
  ]
}
```
```

--------------------------------

### Domain lifecycle management

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sending-api.md

Demonstrates creating a sending domain, updating it with tracking options, sending setup instructions, and retrieving all sending domains.

```APIDOC
## Domain lifecycle management

### Description
This example shows how to create a sending domain, update its tracking settings, send setup instructions, and retrieve all sending domains using the Mailtrap PHP SDK.

### Methods
- `createSendingDomain(string $domainName)` - Creates a new sending domain.
- `updateSendingDomain(int $domainId, UpdateDomain $update)` - Updates an existing sending domain.
- `sendDomainSetupInstructions(int $domainId, string $email)` - Sends setup instructions to a specified email.
- `getSendingDomains()` - Retrieves all sending domains for the account.

### Parameters
#### createSendingDomain
- **domainName** (string) - Required - The domain name to create (e.g., 'example.com').

#### updateSendingDomain
- **domainId** (int) - Required - The ID of the domain to update.
- **update** (UpdateDomain) - Required - An `UpdateDomain` DTO with fields: `openTrackingEnabled`, `clickTrackingEnabled`, `trackingOptOutEnabled` (all booleans).

#### sendDomainSetupInstructions
- **domainId** (int) - Required - The ID of the domain.
- **email** (string) - Required - The email address to receive setup instructions.

#### getSendingDomains
- No parameters.

### Request Example
```php
use Mailtrap\DTO\Request\Domain\UpdateDomain;
use Mailtrap\Helper\ResponseHelper;
use Mailtrap\MailtrapClient;

$domains = (new MailtrapClient(new Config(getenv('MAILTRAP_API_KEY'))))
    ->sending()->domains($accountId);

$created = ResponseHelper::toArray($domains->createSendingDomain('example.com'));
$domainId = $created['sending_domain']['id'];

$domains->updateSendingDomain($domainId, new UpdateDomain(
    openTrackingEnabled: true,
    clickTrackingEnabled: true,
    trackingOptOutEnabled: true,
));
$domains->sendDomainSetupInstructions($domainId, 'admin@example.com');
var_dump(ResponseHelper::toArray($domains->getSendingDomains()));
```

### Response
#### Success Response
- **createSendingDomain** - Returns an array with a `sending_domain` key containing the created domain object (including `id`).
- **getSendingDomains** - Returns an array of sending domain objects.

#### Response Example
```json
{
  "sending_domain": {
    "id": 123,
    "name": "example.com",
    "status": "active"
  }
}
```
```

--------------------------------

### Basic inbound navigation example

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/inbound-api.md

Shows basic navigation through folders, inboxes, messages, and threads. It creates a folder and inbox, lists messages with pagination using lastId, and lists threads. Requires MAILTRAP_API_KEY environment variable.

```php
use Mailtrap\DTO\Request\Inbound\CreateInboundFolder;
use Mailtrap\DTO\Request\Inbound\CreateInboundInbox;
use Mailtrap\Helper\ResponseHelper;
use Mailtrap\MailtrapClient;

$inbound = (new MailtrapClient(new Config(getenv('MAILTRAP_API_KEY'))))->inbound();

$folder = ResponseHelper::toArray($inbound->folders()->create(new CreateInboundFolder('Support')));
$folderId = $folder['id'];

$inbox = ResponseHelper::toArray($inbound->inboxes($folderId)
    ->create(new CreateInboundInbox('Info', domainId: null)));     // hosted inbox
$inboxId = $inbox['id'];

$messages = $inbound->messages($inboxId);
$list = ResponseHelper::toArray($messages->getList());
$next  = ResponseHelper::toArray($messages->getList(lastId: $list['last_id'])); // page 2

$threads = $inbound->threads($inboxId);
var_dump(ResponseHelper::toArray($threads->getList()));
```

--------------------------------

### Webhook creation with full vocabulary and inbound inbox creation

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/dto-webhook-inbound.md

Example of creating a webhook with all available options (url, webhookType, eventTypes, payloadFormat, sendingStream, active) and creating an inbound catch-all inbox with a domainId.

```php
use Mailtrap\DTO\Request\Webhook\CreateWebhook;
use Mailtrap\DTO\Request\Webhook\Webhook;

$webhooks->createWebhook(new CreateWebhook(
    url: 'https://app.example.com/mailtrap-hook',
    webhookType: Webhook::TYPE_EMAIL_SENDING,
    eventTypes: [Webhook::EVENT_DELIVERY, Webhook::EVENT_BOUNCE, Webhook::EVENT_SPAM_COMPLAINT],
    payloadFormat: Webhook::PAYLOAD_FORMAT_JSONLINES,
    sendingStream: Webhook::SENDING_STREAM_TRANSACTIONAL,
    active: true,
));

// Inbound catch-all inbox:
$inbound->inboxes($folderId)->create(new CreateInboundInbox('Orders', domainId: 77));
```

--------------------------------

### GET /api/inbound/folders

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/endpoints.md

Retrieves a list of all inbound folders.

```APIDOC
## GET /api/inbound/folders

### Description
Retrieves a list of all inbound folders.

### Method
GET

### Endpoint
/api/inbound/folders

### Response
#### Success Response (200)
- **folders** (array) - List of folder objects

#### Response Example
```json
[
  {
    "id": 1,
    "name": "Inbox"
  }
]
```
```

--------------------------------

### Paging and deletion with error handling

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/suppressions-api.md

Error handling example showing how to page through tracking opt-outs using the last_id cursor and how to delete a suppression and a tracking opt-out, catching HttpClientException for errors like 404 or 403.

```php
use Mailtrap\DTO\Request\TrackingOptOut\TrackingOptOutsFilter;
use Mailtrap\Exception\HttpClientException;

// Page through opt-outs with the last_id cursor:
$page = ResponseHelper::toArray($optOuts->getTrackingOptOuts(
    new TrackingOptOutsFilter(lastId: $previousLastId)
));

try {
    $suppr->deleteSuppression($created['id']);
    $optOuts->deleteTrackingOptOut($optOut['id']);
} catch (HttpClientException $e) {
    // 404 — already deleted; 403 — insufficient token permissions, etc.
    echo 'Delete failed: ', $e->getMessage(), "\n";
}
```

--------------------------------

### GET /api/inbound/folders/{folder_id}

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/endpoints.md

Retrieves a specific inbound folder by its ID.

```APIDOC
## GET /api/inbound/folders/{folder_id}

### Description
Retrieves a specific inbound folder by its ID.

### Method
GET

### Endpoint
/api/inbound/folders/{folder_id}

### Parameters
#### Path Parameters
- **folder_id** (integer) - Required - The ID of the folder to retrieve.

### Response
#### Success Response (200)
- **id** (integer) - Folder ID
- **name** (string) - Folder name

#### Response Example
```json
{
  "id": 1,
  "name": "Inbox"
}
```
```

--------------------------------

### Basic suppression and tracking opt-out operations

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/suppressions-api.md

Basic usage example showing how to list suppressions by email, filter with a SuppressionsFilter, create a suppression, and create a tracking opt-out. Requires a valid MAILTRAP_API_KEY environment variable and an account ID.

```php
use Mailtrap\DTO\Request\Suppression\CreateSuppression;
use Mailtrap\DTO\Request\Suppression\Suppression;
use Mailtrap\DTO\Request\Suppression\SuppressionsFilter;
use Mailtrap\Helper\ResponseHelper;
use Mailtrap\MailtrapClient;

$client  = new MailtrapClient(new Config(getenv('MAILTRAP_API_KEY')));
$suppr   = $client->sending()->suppressions($accountId);
$optOuts = $client->sending()->trackingOptOuts();

// string filter = exact email search
$byEmail = ResponseHelper::toArray($suppr->getSuppressions('spammer@example.com'));

// full filter set
$filtered = ResponseHelper::toArray($suppr->getSuppressions(new SuppressionsFilter(
    email: 'spammer@example.com',
    startTime: '2026-01-01T00:00:00Z',
    lastId: null,
)));

$created = ResponseHelper::toArray($suppr->createSuppression(new CreateSuppression(
    email: 'spammer@example.com',
    domainId: 77,
    sendingStream: Suppression::SENDING_STREAM_TRANSACTIONAL,
    type: Suppression::TYPE_MANUAL_IMPORT,
)));

$optOut = ResponseHelper::toArray($optOuts->createTrackingOptOut(new CreateTrackingOptOut(
    email: 'analytics-opt-out@example.com', domainId: 77,
)));
```

--------------------------------

### GET /api/inbound/inboxes/{inbox_id}/messages/{message_id}

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/endpoints.md

Retrieves a specific message by its ID.

```APIDOC
## GET /api/inbound/inboxes/{inbox_id}/messages/{message_id}

### Description
Retrieves a specific message by its ID.

### Method
GET

### Endpoint
/api/inbound/inboxes/{inbox_id}/messages/{message_id}

### Parameters
#### Path Parameters
- **inbox_id** (integer) - Required - The ID of the inbox.
- **message_id** (integer) - Required - The ID of the message.

### Response
#### Success Response (200)
- **id** (integer) - Message ID
- **subject** (string) - Message subject

#### Response Example
```json
{
  "id": 1,
  "subject": "Hello"
}
```
```

--------------------------------

### Valid MAILER_DSN examples for mailtrap+sdk

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/bridge.md

Shows four valid MAILER_DSN environment variable formats for the mailtrap+sdk scheme. The first uses the default host, the next two specify send and bulk hosts, and the last uses the sandbox host with a required inboxId query parameter.

```text
MAILER_DSN=mailtrap+sdk://YOUR_API_KEY_HERE@default
MAILER_DSN=mailtrap+sdk://YOUR_API_KEY_HERE@send.api.mailtrap.io
MAILER_DSN=mailtrap+sdk://YOUR_API_KEY_HERE@bulk.api.mailtrap.io
MAILER_DSN=mailtrap+sdk://YOUR_API_KEY_HERE@sandbox.api.mailtrap.io?inboxId=1000001
```

--------------------------------

### GET /api/inbound/folders/{folder_id}/inboxes

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/endpoints.md

Retrieves a list of inboxes within a specific folder.

```APIDOC
## GET /api/inbound/folders/{folder_id}/inboxes

### Description
Retrieves a list of inboxes within a specific folder.

### Method
GET

### Endpoint
/api/inbound/folders/{folder_id}/inboxes

### Parameters
#### Path Parameters
- **folder_id** (integer) - Required - The ID of the folder.

### Response
#### Success Response (200)
- **inboxes** (array) - List of inbox objects

#### Response Example
```json
[
  {
    "id": 1,
    "name": "Inbox"
  }
]
```
```

--------------------------------

### GET /api/inbound/folders/{folder_id}/inboxes/{inbox_id}

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/endpoints.md

Retrieves a specific inbox within a folder.

```APIDOC
## GET /api/inbound/folders/{folder_id}/inboxes/{inbox_id}

### Description
Retrieves a specific inbox within a folder.

### Method
GET

### Endpoint
/api/inbound/folders/{folder_id}/inboxes/{inbox_id}

### Parameters
#### Path Parameters
- **folder_id** (integer) - Required - The ID of the folder.
- **inbox_id** (integer) - Required - The ID of the inbox.

### Response
#### Success Response (200)
- **id** (integer) - Inbox ID
- **name** (string) - Inbox name

#### Response Example
```json
{
  "id": 1,
  "name": "Inbox"
}
```
```

--------------------------------

### Domain class definition

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sending-api.md

Defines the Domain class, which extends AbstractApi and implements SendingInterface. The constructor accepts a ConfigInterface and an account ID. Methods manage sending domains, including listing, creating, retrieving, updating, deleting, and sending setup instructions.

```php
class Domain extends AbstractApi implements SendingInterface
{
    public function __construct(ConfigInterface $config, private int $accountId)

    public function getSendingDomains(): ResponseInterface
    public function createSendingDomain(string $domainName): ResponseInterface
    public function getDomainById(int $domainId): ResponseInterface
    public function updateSendingDomain(int $domainId, UpdateDomain $domain): ResponseInterface
    public function deleteSendingDomain(int $domainId): ResponseInterface
    public function sendDomainSetupInstructions(int $domainId, string $email): ResponseInterface
}
```

--------------------------------

### GET /api/inbound/inboxes/{inbox_id}/messages

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/endpoints.md

Retrieves a list of messages in an inbox, with optional cursor pagination.

```APIDOC
## GET /api/inbound/inboxes/{inbox_id}/messages

### Description
Retrieves a list of messages in an inbox, with optional cursor pagination.

### Method
GET

### Endpoint
/api/inbound/inboxes/{inbox_id}/messages

### Parameters
#### Path Parameters
- **inbox_id** (integer) - Required - The ID of the inbox.

#### Query Parameters
- **last_id** (integer) - Optional - Cursor for pagination, returns messages after this ID.

### Response
#### Success Response (200)
- **messages** (array) - List of message objects

#### Response Example
```json
[
  {
    "id": 1,
    "subject": "Hello"
  }
]
```
```

--------------------------------

### Error Handling for Campaign Lifecycle Actions

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/email-campaign-api.md

Shows how to handle errors when starting, cancelling, or deleting a campaign. The API returns 422 if the campaign lacks body_html or is not in draft state; cancelling/resetting only works for scheduled campaigns, and deletion is draft-only with 204 on success.

```php
use Mailtrap\Exception\HttpClientException;

try {
    $campaigns->startEmailCampaign($campaignId);
} catch (HttpClientException $e) {
    // e.g. 422 when the campaign has no body_html yet, or is not in draft state
    echo 'Could not start: ', $e->getMessage(), "\n";
}

// Cancelling/resetting only makes sense for scheduled campaigns; the API
// rejects it with 4xx otherwise — caught with the same exception type.
try {
    $campaigns->cancelEmailCampaign($campaignId);
    $campaigns->deleteEmailCampaign($campaignId);   // draft only; 204 on success
} catch (HttpClientException $e) {
    echo 'Lifecycle error: ', $e->getMessage(), "\n";
}
```

--------------------------------

### Billing class skeleton

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/general-api.md

Defines the Billing API class. Constructor requires a config and account ID. getBillingUsage() calls GET /api/accounts/{accountId}/billing/usage to retrieve current billing cycle usage for Email Testing and Email Sending.

```php
class Billing extends AbstractApi implements GeneralInterface
{
    public function __construct(ConfigInterface $config, private int $accountId)

    public function getBillingUsage(): ResponseInterface

    public function getAccountId(): int
}
```

--------------------------------

### EmailCampaign class definition

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/email-campaign-api.md

Defines the EmailCampaign class extending AbstractApi and implementing GeneralInterface. Constructor accepts ConfigInterface and an account ID (used for consistency; actual account resolved from token). Methods cover CRUD, start, schedule, cancel, terminate, reset, and stats operations, all returning ResponseInterface.

```php
class EmailCampaign extends AbstractApi implements GeneralInterface
{
    public function __construct(ConfigInterface $config, private int $accountId)

    public function getEmailCampaigns(
        ?int $perPage = null,
        ?string $search = null,
        ?int $token = null
    ): ResponseInterface
    public function getEmailCampaign(int $emailCampaignId): ResponseInterface
    public function createEmailCampaign(CreateEmailCampaign $emailCampaign): ResponseInterface
    public function updateEmailCampaign(int $emailCampaignId, UpdateEmailCampaign $emailCampaign): ResponseInterface
    public function deleteEmailCampaign(int $emailCampaignId): ResponseInterface
    public function startEmailCampaign(int $emailCampaignId): ResponseInterface
    public function scheduleEmailCampaign(int $emailCampaignId, string|\DateTimeInterface $datetime): ResponseInterface
    public function cancelEmailCampaign(int $emailCampaignId): ResponseInterface
    public function terminateEmailCampaign(int $emailCampaignId): ResponseInterface
    public function resetEmailCampaign(int $emailCampaignId): ResponseInterface
    public function getEmailCampaignStats(
        int $emailCampaignId,
        ?string $startDate = null,
        ?string $endDate = null
    ): ResponseInterface

    public function getAccountId(): int
}
```

--------------------------------

### GET /api/accounts/{accountId}/suppressions

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/suppressions-api.md

Lists or searches suppressions for a given account. Supports filtering by email, start time, and pagination cursor.

```APIDOC
## [GET] /api/accounts/{accountId}/suppressions

### Description
List or search suppressions for a given account. Returns up to 1000 suppressions per request.

### Method
GET

### Endpoint
/api/accounts/{accountId}/suppressions

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The account ID.

#### Query Parameters
- **email** (string) - Optional - Exact email to search for. Provided when the `$filter` argument is a non-empty string.
- **start_time** (string) - Optional - Start time for filtering. Provided when using `SuppressionsFilter`.
- **last_id** (string) - Optional - Cursor for pagination. Provided when using `SuppressionsFilter`.

### Response
#### Success Response (200)
- **suppressions** (array) - List of suppression objects.

#### Response Example
```json
{
  "suppressions": [
    {
      "id": "string",
      "email": "string",
      "type": "string",
      "created_at": "string"
    }
  ]
}
```
```

--------------------------------

### Generate WelcomeMail Mailable with Artisan

Source: https://github.com/mailtrap/mailtrap-php/blob/main/src/Bridge/Laravel/README.md

Run this Artisan command to generate a new Mailable class named WelcomeMail. This is the first step before customizing the email.

```bash
php artisan make:mail WelcomeMail
```

--------------------------------

### GET /api/accounts/{accountId}/inboxes

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sandbox-api.md

Lists all inboxes for the specified account.

```APIDOC
## GET /api/accounts/{accountId}/inboxes

### Description
List inboxes for the account.

### Method
GET

### Endpoint
/api/accounts/{accountId}/inboxes

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The account ID.

### Response
#### Success Response (200)
- **inboxes** (array) - List of inbox objects.

#### Response Example
```json
[
  {
    "id": 1,
    "name": "Inbox 1"
  }
]
```
```

--------------------------------

### GET /api/accounts/{accountId}/stats/date

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sending-api.md

Retrieves statistics grouped by date.

```APIDOC
## GET /api/accounts/{accountId}/stats/date

### Description
Retrieves statistics grouped by date.

### Method
GET

### Endpoint
/api/accounts/{accountId}/stats/date

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The ID of the account.

#### Query Parameters
- **start_date** (string) - Required - Window start (YYYY-MM-DD).
- **end_date** (string) - Required - Window end (YYYY-MM-DD).
- **sending_domain_ids** (array) - Optional - Filter by domain ids.
- **sending_streams** (array) - Optional - Filter by streams (transactional, bulk).
- **categories** (array) - Optional - Filter by categories.
- **email_service_providers** (array) - Optional - Filter by ESPs.

### Response
#### Success Response (200)
- **stats** (object) - Statistics grouped by date.

#### Response Example
{
  "stats": {}
}
```

--------------------------------

### GET /api/accounts/{accountId}/stats/categories

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sending-api.md

Retrieves statistics grouped by category.

```APIDOC
## GET /api/accounts/{accountId}/stats/categories

### Description
Retrieves statistics grouped by category.

### Method
GET

### Endpoint
/api/accounts/{accountId}/stats/categories

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The ID of the account.

#### Query Parameters
- **start_date** (string) - Required - Window start (YYYY-MM-DD).
- **end_date** (string) - Required - Window end (YYYY-MM-DD).
- **sending_domain_ids** (array) - Optional - Filter by domain ids.
- **sending_streams** (array) - Optional - Filter by streams (transactional, bulk).
- **categories** (array) - Optional - Filter by categories.
- **email_service_providers** (array) - Optional - Filter by ESPs.

### Response
#### Success Response (200)
- **stats** (object) - Statistics grouped by category.

#### Response Example
{
  "stats": {}
}
```

--------------------------------

### GET /api/accounts/{accountId}/contacts/fields

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/contact-api.md

Retrieves all custom contact fields.

```APIDOC
## GET /api/accounts/{accountId}/contacts/fields

### Description
Retrieves all custom contact fields.

### Method
GET

### Endpoint
/api/accounts/{accountId}/contacts/fields

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The account ID.

### Response
#### Success Response (200)
- Returns a list of custom fields.

#### Response Example
```json
[
  {
    "id": 1,
    "name": "Field Name",
    "data_type": "string",
    "merge_tag": "field_name"
  }
]
```
```

--------------------------------

### Send Welcome Mail via Artisan Command

Source: https://github.com/mailtrap/mailtrap-php/blob/main/src/Bridge/Laravel/README.md

Executes the registered 'send-welcome-mail' Artisan command to send the email. This command triggers the Mail::to(...)->send(...) call defined in the console route.

```bash
php artisan send-welcome-mail
```

--------------------------------

### GET /api/accounts/{accountId}/inboxes/{inboxId}

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sandbox-api.md

Retrieves attributes of a specific inbox.

```APIDOC
## GET /api/accounts/{accountId}/inboxes/{inboxId}

### Description
Get inbox attributes.

### Method
GET

### Endpoint
/api/accounts/{accountId}/inboxes/{inboxId}

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The account ID.
- **inboxId** (integer) - Required - The inbox ID.

### Response
#### Success Response (200)
- **inbox** (object) - The inbox object with its attributes.

#### Response Example
```json
{
  "id": 1,
  "name": "Inbox 1",
  "email_username": "user@example.com"
}
```
```

--------------------------------

### GET /api/accounts/{accountId}/projects/{projectId}

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sandbox-api.md

Retrieves a specific project and its inboxes.

```APIDOC
## GET /api/accounts/{accountId}/projects/{projectId}

### Description
Retrieves a specific project and its inboxes.

### Method
GET

### Endpoint
/api/accounts/{accountId}/projects/{projectId}

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The account ID.
- **projectId** (integer) - Required - The project ID.

### Response
#### Success Response (200)
- **project** (object) - The project details.

#### Response Example
{
  "project": {}
}
```

--------------------------------

### Register Artisan Command to Send Welcome Mail

Source: https://github.com/mailtrap/mailtrap-php/blob/main/src/Bridge/Laravel/README.md

Registers a console command 'send-welcome-mail' that sends the WelcomeMail to a test receiver. Includes commented-out code for using a specific mailer 'mailtrap-sdk' if it is not the default.

```php
# app/routes/console.php
<?php

use App\Mail\WelcomeMail;
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\Mail;

/*
|--------------------------------------------------------------------------
| Console Routes
|--------------------------------------------------------------------------
|
*/

Artisan::command('send-welcome-mail', function () {
    Mail::to('testreceiver@gmail.com')->send(new WelcomeMail("Jon"));
    
    // Also, you can use specific mailer if your default mailer is not "mailtrap-sdk" but you want to use it for welcome mails
    // Mail::mailer('mailtrap-sdk')->to('testreceiver@gmail.com')->send(new WelcomeMail("Jon"));
})->purpose('Send welcome mail');
```

--------------------------------

### GET /api/accounts/{accountId}/stats/domains

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sending-api.md

Retrieves statistics grouped by sending domain.

```APIDOC
## GET /api/accounts/{accountId}/stats/domains

### Description
Retrieves statistics grouped by sending domain.

### Method
GET

### Endpoint
/api/accounts/{accountId}/stats/domains

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The ID of the account.

#### Query Parameters
- **start_date** (string) - Required - Window start (YYYY-MM-DD).
- **end_date** (string) - Required - Window end (YYYY-MM-DD).
- **sending_domain_ids** (array) - Optional - Filter by domain ids.
- **sending_streams** (array) - Optional - Filter by streams (transactional, bulk).
- **categories** (array) - Optional - Filter by categories.
- **email_service_providers** (array) - Optional - Filter by ESPs.

### Response
#### Success Response (200)
- **stats** (object) - Statistics grouped by domain.

#### Response Example
{
  "stats": {}
}
```

--------------------------------

### Project class definition

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sandbox-api.md

Defines the Project class extending AbstractApi and implementing SandboxInterface. Includes constructor with account ID, methods for listing, retrieving, creating, deleting, and updating projects, and a getter for the account ID. Base path is /api/accounts/{accountId}/projects.

```php
class Project extends AbstractApi implements SandboxInterface
{
    public function __construct(ConfigInterface $config, private int $accountId)

    public function getList(): ResponseInterface
    public function getById(int $projectId): ResponseInterface
    public function create(string $projectName): ResponseInterface
    public function delete(int $projectId): ResponseInterface
    public function updateName(int $projectId, string $projectName): ResponseInterface

    public function getAccountId(): int
}
```

--------------------------------

### GET /api/accounts/{accountId}/sending_domains

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sending-api.md

Lists all sending domains for the specified account.

```APIDOC
## GET /api/accounts/{accountId}/sending_domains

### Description
Lists all sending domains for the specified account.

### Method
GET

### Endpoint
/api/accounts/{accountId}/sending_domains

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The account ID.

### Response
#### Success Response (200)
- Returns a list of sending domains.

#### Response Example
(No example provided in source)
```

--------------------------------

### POST /api/accounts/{accountId}/projects

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sandbox-api.md

Creates a new project.

```APIDOC
## POST /api/accounts/{accountId}/projects

### Description
Creates a new project.

### Method
POST

### Endpoint
/api/accounts/{accountId}/projects

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The account ID.

#### Request Body
- **project** (object) - Required - The project object.
- **project.name** (string) - Required - The project name.

### Request Example
{
  "project": {
    "name": "string"
  }
}

### Response
#### Success Response (201)
- **project** (object) - The created project.

#### Response Example
{
  "project": {}
}
```

--------------------------------

### GET /api/accounts/{accountId}/projects

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sandbox-api.md

Retrieves a list of projects and their inboxes that the token can access.

```APIDOC
## GET /api/accounts/{accountId}/projects

### Description
Retrieves a list of projects and their inboxes that the token can access.

### Method
GET

### Endpoint
/api/accounts/{accountId}/projects

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The account ID.

### Response
#### Success Response (200)
- **projects** (array) - List of projects.

#### Response Example
{
  "projects": []
}
```

--------------------------------

### Configure MAILER_DSN for sandbox

Source: https://github.com/mailtrap/mailtrap-php/blob/main/src/Bridge/Symfony/README.md

Use this DSN for sandbox testing. Replace YOUR_API_KEY_HERE and inboxId with your actual API key and inbox ID.

```bash
MAILER_DSN=mailtrap+sdk://YOUR_API_KEY_HERE@sandbox.api.mailtrap.io?inboxId=1000001
```

--------------------------------

### Basic MailtrapClient creation with explicit layer selection

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/mailtrap-client.md

Creates a full-featured Mailtrap client using the MailtrapClient constructor with an API key from the MAILTRAP_API_KEY environment variable. It demonstrates accessing transactional sending, sandbox inboxes, and inbound messages, then sends an email using MailtrapEmail and Symfony Mime Address.

```php
use Mailtrap\MailtrapClient;
use Mailtrap\Mime\MailtrapEmail;
use Symfony\Component\Mime\Address;

$client  = new MailtrapClient(new Config(getenv('MAILTRAP_API_KEY')));
$emails  = $client->sending()->emails();        // transactional stream
$inboxes = $client->sandbox()->inboxes(123);    // sandbox, account id 123
$msg     = $client->inbound()->messages(456);   // inbound inbox 456

$response = $emails->send(
    (new MailtrapEmail())->from(new Address('from@example.com'))
                         ->to(new Address('to@example.com'))
                         ->subject('Hi')
                         ->text('Hello')
);
```

--------------------------------

### GET /api/accounts/{accountId}/stats/email_service_providers

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sending-api.md

Retrieves statistics grouped by email service provider.

```APIDOC
## GET /api/accounts/{accountId}/stats/email_service_providers

### Description
Retrieves statistics grouped by email service provider.

### Method
GET

### Endpoint
/api/accounts/{accountId}/stats/email_service_providers

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The ID of the account.

#### Query Parameters
- **start_date** (string) - Required - Window start (YYYY-MM-DD).
- **end_date** (string) - Required - Window end (YYYY-MM-DD).
- **sending_domain_ids** (array) - Optional - Filter by domain ids.
- **sending_streams** (array) - Optional - Filter by streams (transactional, bulk).
- **categories** (array) - Optional - Filter by categories.
- **email_service_providers** (array) - Optional - Filter by ESPs.

### Response
#### Success Response (200)
- **stats** (object) - Statistics grouped by ESP.

#### Response Example
{
  "stats": {}
}
```

--------------------------------

### GET /api/domains/{domainId}/company_info

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sending-api.md

Retrieves the current company information for a specific domain.

```APIDOC
## GET /api/domains/{domainId}/company_info

### Description
Retrieves the current company information for a specific domain.

### Method
GET

### Endpoint
/api/domains/{domainId}/company_info

### Parameters
#### Path Parameters
- **domainId** (integer) - Required - The ID of the domain.

### Response
#### Success Response (200)
- **company_info** (object) - The company information object.

#### Response Example
{
  "company_info": {}
}
```

--------------------------------

### Basic Mailtrap config with sandbox host override

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/config.md

Creates a Config with the API key from the MAILTRAP_API_KEY environment variable, overrides the host to the sandbox endpoint, and instantiates a MailtrapSandboxClient to fetch the list of inboxes.

```php
use Mailtrap\Config;
use Mailtrap\MailtrapSandboxClient;

$config = (new Config(getenv('MAILTRAP_API_KEY')))
    ->setHost('sandbox.api.mailtrap.io');

$client = new MailtrapSandboxClient($config);
$response = $client->inboxes()->getList();
```

--------------------------------

### MailtrapClient::__construct (constructor)

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/mailtrap-client.md

Constructor inherited from AbstractMailtrapClient. Accepts a single ConfigInterface argument to initialize the client.

```APIDOC
## MailtrapClient::__construct (constructor)

### Description
Constructor inherited from AbstractMailtrapClient. Accepts a single ConfigInterface argument to initialize the client.

### Method
CONSTRUCTOR

### Signature
```php
public function __construct(protected ConfigInterface $config)
```

### Parameters
- **config** (ConfigInterface) - Required - The configuration instance used to build the client.

### Notes
There is no explicit constructor on `MailtrapClient`; it inherits this one from `AbstractMailtrapClient`.
```

--------------------------------

### GET /api/accounts/{accountId}/sending_domains/{domainId}

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sending-api.md

Retrieves a single sending domain by its ID.

```APIDOC
## GET /api/accounts/{accountId}/sending_domains/{domainId}

### Description
Retrieves a single sending domain by its ID.

### Method
GET

### Endpoint
/api/accounts/{accountId}/sending_domains/{domainId}

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The account ID.
- **domainId** (integer) - Required - The domain ID.

### Response
#### Success Response (200)
- Returns the domain details.

#### Response Example
(No example provided in source)
```

--------------------------------

### GET /api/inbound/inboxes/{inboxId}/threads/{threadId}

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/inbound-api.md

Retrieves a single conversation thread by its ID.

```APIDOC
## GET /api/inbound/inboxes/{inboxId}/threads/{threadId}

### Description
Retrieves a single conversation thread by its ID.

### Method
GET

### Endpoint
/api/inbound/inboxes/{inboxId}/threads/{threadId}

### Parameters
#### Path Parameters
- **inboxId** (integer) - Required - The ID of the inbox containing the thread.
- **threadId** (string) - Required - The ID of the thread to retrieve.

### Request Example
GET /api/inbound/inboxes/123/threads/thread_456

### Response
#### Success Response (200)
- **id** (string) - The thread ID.
- **subject** (string) - The thread subject.

#### Response Example
{
  "id": "thread_456",
  "subject": "Re: Your ticket"
}
```

--------------------------------

### GET /api/accounts/{accountId}/contacts/imports/{importId}

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/contact-api.md

Retrieves the status of a contact import job.

```APIDOC
## GET /api/accounts/{accountId}/contacts/imports/{importId}

### Description
Retrieves the status of a contact import job.

### Method
GET

### Endpoint
/api/accounts/{accountId}/contacts/imports/{importId}

### Parameters
#### Path Parameters
- **accountId** (integer) - Required - The account ID.
- **importId** (integer) - Required - The import job ID.

### Response
#### Success Response (200)
- Returns the import job status.

#### Response Example
```json
{
  "id": 1,
  "status": "completed"
}
```
```

--------------------------------

### Create API token with permissions and expiration

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/dto-request.md

Creates a permissions object with create/update and destroy permissions for account, inbox, and mail-send domain resources, sets a token expiration one year from now, and calls createApiToken with the permissions and expiration. The toPayload() method returns the JSON 'resources' payload.

```php
use Mailtrap\DTO\Request\ApiToken\TokenExpiration;
use Mailtrap\DTO\Request\Permission\CreateOrUpdatePermission;
use Mailtrap\DTO\Request\Permission\DestroyPermission;
use Mailtrap\DTO\Request\Permission\PermissionInterface;
use Mailtrap\DTO\Request\Permission\Permissions;

$permissions = new Permissions(
    new CreateOrUpdatePermission($accountId, PermissionInterface::TYPE_ACCOUNT, 1000),
    new CreateOrUpdatePermission($inboxId,   PermissionInterface::TYPE_INBOX, 500),
    new DestroyPermission($oldDomainId, PermissionInterface::TYPE_MAILSEND_DOMAIN),
);

$exp = TokenExpiration::at(new DateTimeImmutable('+1 year'));
$body = $permissions->toPayload();          // JSON "resources" payload
$apiTokens->createApiToken('CI token', $permissions, $exp);
```

--------------------------------

### Company info validation and stats queries

Source: https://github.com/mailtrap/mailtrap-php/blob/main/_autodocs/api-reference/sending-api.md

Demonstrates creating and updating company info with error handling, and querying stats for a date range and domain.

```APIDOC
## Company info validation and stats queries

### Description
This example shows how to create and update company info for a sending domain, handle validation errors, and query stats for a specific date range and domain.

### Methods
- `createCompanyInfo(CreateCompanyInfo $info)` - Creates company info for a domain.
- `updateCompanyInfo(UpdateCompanyInfo $info)` - Updates company info (requires at least one field).
- `get(string $startDate, string $endDate, array $domainIds, array $eventTypes)` - Retrieves stats for the account.

### Parameters
#### createCompanyInfo
- **info** (CreateCompanyInfo) - Required - DTO with fields: `name`, `address`, `city`, `country`, `zipCode`, `websiteUrl`, `phone`, `infoLevel` (use `CompanyInfo::INFO_LEVEL_BUSINESS`).

#### updateCompanyInfo
- **info** (UpdateCompanyInfo) - Required - DTO with at least one updatable field. Throws `InvalidArgumentException` if no fields provided.

#### get
- **startDate** (string) - Required - Start date in YYYY-MM-DD format.
- **endDate** (string) - Required - End date in YYYY-MM-DD format.
- **domainIds** (array) - Required - Array of domain IDs.
- **eventTypes** (array) - Required - Array of event types (e.g., `['transactional']`).

### Request Example
```php
use Mailtrap\DTO\Request\Domain\CreateCompanyInfo;
use Mailtrap\Exception\HttpClientException;
use Mailtrap\Exception\InvalidArgumentException;

$company = $client->sending()->companyInfo($domainId);
try {
    $company->createCompanyInfo(new CreateCompanyInfo(
        name: 'Acme Inc.', address: '1 Main St', city: 'Springfield',
        country: 'US', zipCode: '12345', websiteUrl: 'https://acme.example',
        phone: '+1-555-0100', infoLevel: CompanyInfo::INFO_LEVEL_BUSINESS,
    ));
} catch (HttpClientException $e) {
    echo 'Company info rejected: ', $e->getMessage(), "\n";
}

try {
    $company->updateCompanyInfo(new UpdateCompanyInfo());
} catch (InvalidArgumentException $e) {
    echo $e->getMessage(), "\n";   // 'At least one updatable field must be provided...'
}

$stats = $client->sending()->stats($accountId);
var_dump(ResponseHelper::toArray($stats->get('2026-08-01', '2026-08-31', [ $domainId ], ['transactional'])));
```

### Response
#### Success Response
- **createCompanyInfo** - Returns the created company info object.
- **updateCompanyInfo** - Returns the updated company info object.
- **get** - Returns an array of stats data.

#### Error Handling
- **HttpClientException** - Thrown when company info is rejected by the server.
- **InvalidArgumentException** - Thrown when updating with no fields provided.

#### Response Example
```json
{
  "stats": {
    "total_emails": 1000,
    "delivered": 950,
    "bounced": 20
  }
}
```
```
Tokens:
Raw