PHPackages fet/postcard-api - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. fet/postcard-api ActiveLibrary[API Development](/categories/api) fet/postcard-api ================ A PHP implementation of the Swiss Postcard API 0.1.1(2y ago)1420MITPHPPHP ^8.1 Since May 4Pushed 2y ago1 watchersCompare [ Source](https://github.com/f-E-T/postcard-api)[ Packagist](https://packagist.org/packages/fet/postcard-api)[ Docs](https://github.com/f-e-t/postcard-api)[ RSS](/packages/fet-postcard-api/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (3)Versions (3)Used By (0) Introduction ============ [](#introduction) The `fet/postcard-api` package is a PHP implementation of the Swiss Postcard API (see [References](#references)). Installation ============ [](#installation) To install this package, use Composer: ``` composer require fet/postcard-api ``` > Make sure you have Composer installed on your system before running this command. Configuration ============= [](#configuration) Create a new `Fet\PostcardApi\PostcardCreator` instance using your API credentials: ``` use Fet\PostcardApi\PostcardCreator; $postcardCreator = PostcardCreator::factory( 'POSTCARD_API_URL', // The base URL of the postcard API 'POSTCARD_API_CAMPAIGN_KEY', // Your postcard API campaign key 'POSTCARD_API_CLIENT_ID', // Your postcard API client ID 'POSTCARD_API_CLIENT_SECRET', // Your postcard API client secret ); ``` Usage ===== [](#usage) Campaign -------- [](#campaign) The campaign API allows you to retrieve information about your campaign. To interact with the campaign API, first obtain the campaign instance from the postcard creator: ``` $campaign = $postcardCreator->getCampaign(); ``` Once you have the campaign instance, you can access its information using the following methods: ``` // get the unique identifier for the campaign $campaign->getCampaignKey(); // get the total quota of postcards allowed in the campaign $campaign->getQuota(); // get the number of postcards already created within the campaign $campaign->getNumberOfCreatedPostcards(); // get the remaining number of postcards that can be created in the campaign $campaign->getNumberOfAvailablePostcards(); ``` Postcard -------- [](#postcard) To use the postcard API, you need to provide recipient and sender address details, the path to the front image of the postcard and the text to be printed on the postcard. Here's an example of how to do this: ``` use Fet\PostcardApi\PostcardCreator; // recipient address details $recipient = [ 'title' => 'Mr.', 'firstname' => 'John', 'lastname' => 'Smith', 'company' => 'ABC Inc.', 'street' => '123 Main St.', 'houseNr' => '456', 'zip' => '12345', 'city' => 'Anytown', 'country' => 'United States', 'poBox' => 'P.O. Box 789', 'additionalAdrInfo' => 'Apt. 789', ]; // sender address details $sender = [ 'firstname' => 'Jane', 'lastname' => 'Doe', 'company' => 'XYZ Corp.', 'street' => '456 Elm St.', 'houseNr' => '789', 'zip' => '67890', 'city' => 'Anyville', ]; // path to the front image $image = 'path-to-image'; // text to be printed on the postcard $senderText = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'; // create the postcard $postcard = $postcardCreator->create($recipient, $sender, $image, $senderText); // approve the postcard $postcard->approve(); ``` > The `$recipient` and `$sender` array have no required key/value pairs, but the `$postcard` instance will return errors and warnings if something went wrong. ### Advanced usage [](#advanced-usage) You can further manipulate the `$postcard` instance if you want: ``` // add a stamp image to the postcard $postcard->addStampImage('path-to-stamp-image'); // add branding text to the postcard $postcard->addBrandingText('branding-text'); // add a branding image to the postcard $postcard->addBrandingImage('path-to-branding-image'); // add a branding QR tag to the postcard, with an optional side text $postcard->addBrandingQrTag('qr-tag-text', 'qr-tag-side-text'); // get a base64-encoded preview image of the front of the postcard $postcard->getFrontPreview()->getImageData(); // get a base64-encoded preview image of the back of the postcard $postcard->getBackPreview()->getImageData(); ``` > The `addBrandingText()`, `addBrandingImage()`, and `addBrandingQrTag()` methods cannot be used in combination with each other, as they will overwrite each other's content. Choose one method to use for your postcard branding. ### Approval [](#approval) The postcard can only be approved if no errors are returned from the API. Otherwise, a `Fet\PostcardApi\Exception\PostcardException.php` exception will be thrown. ### Handling warnings and errors [](#handling-warnings-and-errors) If there are warnings or errors returned from the API during the process of creating a postcard, you can retrieve them as follow: ``` // returns a multidimensional array with warnings $warnings = $postcard->getWarnings(); // returns a multidimensional array with errors $errors = $postcard->getErrors(); ``` Demo ==== [](#demo) Configuration ------------- [](#configuration-1) Before running the demo, you have to edit the `examples/config.php` file: ``` return [ 'url' => 'POSTCARD_API_URL', 'campaign_key' => 'POSTCARD_API_CAMPAIGN_KEY', 'client_id' => 'POSTCARD_API_CLIENT_ID', 'client_secret' => 'POSTCARD_API_CLIENT_SECRET', ]; ``` Running the demo in your browser -------------------------------- [](#running-the-demo-in-your-browser) To launch a demo and see how the postcard API works in action, follow these steps: 1. Start a local PHP development server by running the following command: ``` php -S localhost:8888 -t examples ``` 2. Open your web browser and navigate to the following URL: `http://localhost:8888/` Tests ===== [](#tests) Run the tests with: ``` composer test ``` References ========== [](#references) Technical specifications ------------------------ [](#technical-specifications) - Swagger documentation --------------------- [](#swagger-documentation) - [https://api.post.ch/pcc-doc/doctools/swagger-ui/dist/index.html?url=https://api.post.ch/pcc-doc/doctools/swagger-ui/src/openapi/api.yaml&\_ga=2.187366318.709186670.1679047313-1057897365.1677000967](https://api.post.ch/pcc-doc/doctools/swagger-ui/dist/index.html?url=https://api.post.ch/pcc-doc/doctools/swagger-ui/src/openapi/api.yaml&_ga=2.187366318.709186670.1679047313-1057897365.1677000967) ### Health Score 23 — LowBetter than 27% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity14 Limited adoption so far Community7 Small or concentrated contributor base Maturity44 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~257 days Total 2 Last Release 852d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/dc87555460306e35d17c3ede6ec071a207ba15d59d340a71380fb74b871ad659?d=identicon)[f-E-T](/maintainers/f-E-T) --- Top Contributors [![f-E-T](https://avatars.githubusercontent.com/u/87535893?v=4)](https://github.com/f-E-T "f-E-T (6 commits)") --- Tags apipostcard ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/fet-postcard-api/health.svg) ``` [![Health](https://phpackages.com/badges/fet-postcard-api/health.svg)](https://phpackages.com/packages/fet-postcard-api) ``` ### Alternatives [openai-php/laravel OpenAI PHP for Laravel is a supercharged PHP API client that allows you to interact with the Open AI API 3.7k7.6M74](/packages/openai-php-laravel)[mailchimp/transactional 458.9M16](/packages/mailchimp-transactional)[get-stream/stream-chat A PHP client for Stream Chat (https://getstream.io/chat/) 301.8M2](/packages/get-stream-stream-chat)[convertkit/convertkitapi Kit PHP SDK for the Kit API 2167.1k1](/packages/convertkit-convertkitapi) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)