> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.usglobalmail.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.usglobalmail.com/_mcp/server.

# PHP SDK

## Install

```bash
composer require usgm/sdk
```

Requires PHP 8.1+.

## Initialize

```php
<?php

use Usgm\UsglobalmailClient;

$usgm = new UsglobalmailClient(getenv('USGM_API_KEY')); // never hard-code the key
```

## Usage

```php
<?php

use Usgm\Mails\Requests\MailsListRequest;
use Usgm\Folders\Requests\CreateFolderDto;

// Your account profile
$account = $usgm->account->get();
echo $account->email . PHP_EOL;

// List mail, one page at a time (cursor pagination)
$cursor = null;
do {
    $page = $usgm->mails->list(new MailsListRequest(cursor: $cursor));
    foreach ($page->data as $mail) {
        echo $mail->id . ' ' . $mail->senderName . PHP_EOL;
    }
    $cursor = $page->nextCursor;
} while ($cursor !== null);

// Fetch one item
$mail = $usgm->mails->get('80421');

// Create a folder
$folder = $usgm->folders->create(new CreateFolderDto(name: 'Taxes'));
```

## Error handling

```php
<?php

use Usgm\Exceptions\UsglobalmailApiException;

try {
    $usgm->mails->get('does-not-exist');
} catch (UsglobalmailApiException $err) {
    // getBody() is the RFC 9457 problem+json payload (code, request_id, detail, …)
    error_log($err->getCode() . ' ' . json_encode($err->getBody()));
    throw $err;
}
```

> **Note**
>
> Transient `429` and `5xx` responses are retried automatically with exponential backoff. See
> [Errors](/guides/core-concepts/errors) for the full problem+json contract.