{"id":18547371,"url":"https://github.com/rnevarezc/postal","last_synced_at":"2026-02-25T22:01:40.538Z","repository":{"id":47347614,"uuid":"258598304","full_name":"rnevarezc/postal","owner":"rnevarezc","description":"A lightweight Postal API Client","archived":false,"fork":false,"pushed_at":"2022-07-20T16:33:33.000Z","size":46,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-24T11:21:30.228Z","etag":null,"topics":["api-client-php","php","postal"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rnevarezc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-24T18:56:20.000Z","updated_at":"2024-09-03T22:54:53.000Z","dependencies_parsed_at":"2022-08-29T08:40:30.256Z","dependency_job_id":null,"html_url":"https://github.com/rnevarezc/postal","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnevarezc%2Fpostal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnevarezc%2Fpostal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnevarezc%2Fpostal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnevarezc%2Fpostal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rnevarezc","download_url":"https://codeload.github.com/rnevarezc/postal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248107295,"owners_count":21048894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client-php","php","postal"],"created_at":"2024-11-06T20:29:10.205Z","updated_at":"2026-02-25T22:01:35.502Z","avatar_url":"https://github.com/rnevarezc.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Postal API Client\n\nThis library helps you use the [Postal](https://github.com/atech/postal) API in PHP 7.2 (and above) to send Emails, get Message Details \u0026 Deliveries and Implement Events to handle Server Webhooks.\n\nIt uses [GuzzleHTTP](https://github.com/guzzle/guzzle) client and PSR-7: [HTTP-PSR7 interfaces](https://www.php-fig.org/psr/psr-7/).\n\n## Installation\n\nInstall the library using [Composer](https://getcomposer.org/):\n\n```bash\ncomposer require rnevarezc/postal\n```\n\n## Usage\n\n### Using the Client\n\nYou will need an API Credential from your Postal Installation to use the API Client.\n\n```php\n// Create a new Postal client using the server key of your Postal Installation.\n$client = new \\Postal\\Client('https://postal.yourdomain.com', 'your-api-key');\n\n// Optional: You can add any aditional Headers for your API installation (Maybe Authorization)\n// You just add an array of headers:\n$headers = [\n    'Authorization' =\u003e 'Basic RTYtaO54BGBtcG9yYWwyMDIw'\n];\n\n$client = new \\Postal\\Client('https://postal.yourdomain.com', 'your-api-key', $headers);\n\n// Or you can add them manually to a Client Instance:\n$client-\u003eaddHeaders($headers);\n```\n\n### Sending an Email\n\nSending an email is simple. You can follow the example below:\n\n```php\n// Create a new Mail message with a Hash of attributes:\n$mail = new \\Postal\\Mail\\Mail([\n    'to' =\u003e ['recipient@mail.com', 'rafael@example.com'],\n    'cc' =\u003e 'me@github.com',\n    'from' =\u003e 'me@mail.com',\n    'subject' =\u003e 'A Postal Email!',\n    'plain_body' =\u003e 'This is a test of new Postal Client',\n    'html_body' =\u003e '\u003cp\u003eThis is a HTML body!\u003c/p\u003e'\n]);\n```\n\nOr Create a new mail message and add manually each of the Mail attributes\n\n```php\n$mail = new \\Postal\\Mail\\Mail;\n\n$mail-\u003eaddTo('recipient@example.com');\n\n// You can Add TO, CC, BCC recipients using strings or arrays:\n$mail-\u003eaddTo(['john@example.com', 'testing@example.com']);\n$mail-\u003eaddCc('test@example.com');\n\n// Add any custom headers\n$mail-\u003eaddHeader('X-PHP-Test', 'value');\n\n// Set the Subject, Plain Body, HTML Body, from, and sender manually:\n$mail-\u003esetSubject('My new subject');\n$mail-\u003esetPlainBody('This is a new text');\n$mail-\u003esetHtmlBody('\u003cp\u003eThis is a new text\u003c/p\u003e');\n\n// Finally, when you are ready, send the Message using the client.\n// You can capture the API Response if you like.\n$response = $client-\u003esend($mail);\n// This is a instance of \\Postal\\Response\\Response;\n```\n\nIf you'd like to capture the Messages Dispatched for each recipient of the Mail.\nYou can do it like so:\n\n```php\n//This will return a Hash of 'recipient' =\u003e \\Postal\\Message\\Message Instance\n$messages = $mail-\u003egetMessages();\n\nforeach ($messages as $recipient =\u003e $message){\n    $recipient = $recipient; //recipient@mail.com\n    $id = $message-\u003egetId(); // Ex.: 653621\n    $token = $message-\u003egetToken() // abcdef123\n}\n```\n\n### Getting Message Details\n\nYou can get the Details of a Message using the Client. You just need the Message ID\n\n```php\n// Get the Details of the Message: 653621 of the previous example:\n$response = $client-\u003egetMessageDetails(653621);\n\n// Then use the details:\n$data = $response-\u003egetData(); // This is an array of the Message Details.\n\n// Additionaly you can specify individual _expansions for the Message Detail,\n// or use \"true\" to retreive them all:\n$response = $client-\u003egetMessageDetails(653621, ['status', 'details', 'inspection']);\n\n// OR:\n$response = $client-\u003egetMessageDetails(653621, true);\n// This will get all the expansions provided by the Postal API.\n```\n\n### Getting Message Deliveries\n\nYou can get the Deliveries of a Message using the Client. You just need the Message ID\n\n```php\n// Get the Details of the Message: 653621 of the previous example:\n$response = $client-\u003egetMessageDeliveries(653621);\n// This will return a \\Postal\\Response\\Response instance\n\n// Then use the deliveries structure:\n$data = $response-\u003egetData(); // This is an array of the Message Deliveries\n```\n\n## Events and Webhooks!\n\nThis library provides support for all the type of Payloads that a Postal Installation can send via Webhooks.\n\nYou must configure your postal Installation to send those events to an URL of your choice to be able to use this library.\n\nYou can get more information about Webhooks and Payloads in the [Postal Documentation](https://github.com/postalhq/postal/wiki/Webhook-Events-\u0026-Payloads)\n\n### Message Status Events, Bounces \u0026 Click Events\n\nMessage Status events all receive the same payload (with different data) based on the status of a message.\n\n- ```MessageSent``` - when a message is successfully delivered\n- ```MessageDelayed``` - when a message's delivery has been delayed.\n- ```MessageDeliveryFailed``` - when a message cannot be delivered.\n- ```MessageHeld``` - when a message is held.\n\n\n- If a message bounces, you'll receive the ```MessageBounced``` event.\n\n- If you have click tracking enabled, the ```MessageLinkClicked``` event will tell you that a user has clicked on a link in one of your e-mails.\n\nThe ```Postal\\Events\\Message\\Events``` Class is a Factory that can Parse a Payload of any of these events and build the correct Event Implementation.\n\nCapturing these Events in an Handler (or a Controller) is very easy. You could define a Class in your app and capture the request like this:\n\n```php\n...\nuse Postal\\Events\\Message\\Events;\nuse Postal\\Events\\Message\\MessageEvent;\nuse Psr\\Http\\Message\\RequestInterface;\n\nclass MessageEventController extends Controller\n{\n    /**\n     * Handle Message Event Webhooks\n     *\n     * Postal sends the events via a POST method.\n     *\n     * @param Request $request\n     * ...\n     */\n    public function post(RequestInterface $request) {\n\n       // Here we capture the Event payload provided in the PSR-7\n       // Request and parse it into an Event using the Message Events Factory.\n\n       // @var \\Postal\\Events\\Message\\MessageEvent\n       $event = Events::fromRequest($request);\n\n       // ... Do some Stuff...\n    }\n}\n...\n```\nIf you capture the POST payload in any other way you could send that payload to the Factory directly to build an Event:\n\n```PHP\n$event = Events::fromPayload($array);\n```\n\nIf a invalid Payload is provided, an ```\\Postal\\Exceptions\\InvalidEventPayloadException``` is thrown\n\n#### Using the ```MessageEvent```.\n\nDepending on the Event Type you get an Concrete Implementation of the ```MessageEvent Interface```. The defined types (and their clases) are the same provided by Postal:\n\n```php\n...\ninterface MessageEvent extends Event\n{\n    const SENT = 'Sent';\n    const DELAYED = 'Delayed';\n    const DELIVERY_FAILED = 'DeliveryFailed';\n    const HELD = 'Held';\n    const BOUNCED = 'Bounced';\n    const CLICKED = 'LinkClicked';\n    ...\n}\n```\n- ```getMessage()``` : Returns an instance of the associated ```\\Postal\\Message\\Message``` associated to the event.\n- ```getType()``` : Returns the type of the Event.\n- ```toArray()``` : Returns an array representation of the Event.\n\n\nMessageBounced Event:\n- ```getBounce()```: Returns an instance of ```\\Postal\\Message\\Message``` with the Bounced Message.\n\n### Server Events\n\nIf you'd like to capture a ```DomainDNSError``` event you can use that specific Event Class:\n\n```php\n$event = DomainDNSError::fromPayload($array);\n```\n\nThe same way, if you'd like to capture any kind of SendLimit Event, you can do it via the Static Methods defined in the Factory Class:\n\n```php\n$event = SendLimitApproaching::fromPayload($array);\n```\n\nor\n\n```php\n$event = SendLimitExceeded::fromPayload($array);\n```\n\nThe $event variable will have the correct Event depending on the Payload.\n\nIt is strongly recommended to use different Handlers (or Controllers) by type of Event and don't use a Common webhook URL to handle them all!\n\n\n## API Information\n\nYou can get more information about the Postal API and Payloads in the [Postal Project Wiki](https://github.com/postalhq/postal/wiki/Using-the-API)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frnevarezc%2Fpostal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frnevarezc%2Fpostal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frnevarezc%2Fpostal/lists"}