PHPackages                             decodelabs/telegraph - 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. [Mail & Notifications](/categories/mail)
4. /
5. decodelabs/telegraph

ActiveLibrary[Mail & Notifications](/categories/mail)

decodelabs/telegraph
====================

Simple mailing list manager

v0.5.3(7mo ago)02331MITPHPPHP ^8.4CI passing

Since Jun 10Pushed 5mo agoCompare

[ Source](https://github.com/decodelabs/telegraph)[ Packagist](https://packagist.org/packages/decodelabs/telegraph)[ RSS](/packages/decodelabs-telegraph/feed)WikiDiscussions develop Synced 1mo ago

READMEChangelog (10)Dependencies (14)Versions (26)Used By (1)

Telegraph
=========

[](#telegraph)

[![PHP from Packagist](https://camo.githubusercontent.com/af5677f22320ebe7be52061a47092aa7eb9ccaf9e6ee9fd2af854ae346b93256/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6465636f64656c6162732f74656c6567726170683f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/telegraph)[![Latest Version](https://camo.githubusercontent.com/d0438f6ed9623d83e9d696047bf22db4a9d3e04cf3723e1130e3df2c42426385/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6465636f64656c6162732f74656c6567726170682e7376673f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/telegraph)[![Total Downloads](https://camo.githubusercontent.com/ae85ce1765a44329ef41ebedda51b30139b7d5241d248e2b1922dd0b5376e103/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6465636f64656c6162732f74656c6567726170682e7376673f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/telegraph)[![GitHub Workflow Status](https://camo.githubusercontent.com/749ec6629198996aaadadc09534e728b4cf431feff38f044223cd059fb8ac8db/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6465636f64656c6162732f74656c6567726170682f696e746567726174652e796d6c3f6272616e63683d646576656c6f70)](https://github.com/decodelabs/telegraph/actions/workflows/integrate.yml)[![PHPStan](https://camo.githubusercontent.com/e25c14ce011edabdd0fbd2e10415b41cc5d66ed11ef3e5b7edd074c5bdd35a2d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d656e61626c65642d3434434331312e7376673f6c6f6e6743616368653d74727565267374796c653d666c6174)](https://github.com/phpstan/phpstan)[![License](https://camo.githubusercontent.com/c1d30d8437c7a00dfde7068b19af9dd94df666cff97a0406b04e2de465c1af10/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6465636f64656c6162732f74656c6567726170683f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/telegraph)

### Simple mailing list manager

[](#simple-mailing-list-manager)

Telegraph provides a simple and opinionated way to manage and interact with third party mailing list services, normalising the intricacies of each service into a consistent API.

---

Installation
------------

[](#installation)

This package requires PHP 8.4 or higher.

Install via Composer:

```
composer require decodelabs/telegraph
```

Setup
-----

[](#setup)

The system is designed as a simplified abstraction in front of third party mailing list services. It doesn't aim to be a full implementation of all the features of each service, but rather to provide a consistent interface for managing the most common operations.

### Configuration

[](#configuration)

Configuration can be defined by any class that implements the `DecodeLabs\Telegraph\Config` interface. The package provides a [Dovetail](https://github.com/decodelabs/dovetail) implementation out of the box however it can be easily replaced with a custom implementation.

```
use DecodeLabs\Monarch;
use DecodeLabs\Telegraph;
use DecodeLabs\Telegraph\Config;

Monarch::getKingdom()->container->setType(Config::class, MyConfig::class);
$telegraph = Monarch::getService(Telegraph::class);
```

The configuration class must provide access to a list of sources which map a source name to an `Adapter` name, settings that allow the adapter to operate and the ID of the specific list to use from that service.

With the default `Dovetail` implementation, your configuration file could look like this:

```
use DecodeLabs\Dovetail\Env;

return [
    'main' => [
        'adapter' => 'Mailchimp',
        'apiKey' => Env::asString('MAILCHIMP_API_KEY'),
        'list' => 'abc123abc123'
    ]
];
```

### Cache

[](#cache)

Telegraph expects to be able to cache the results of API calls to avoid making unnecessary network requests. The main context accepts an instance of a `Psr\Cache\CacheItemPoolInterface` to use for caching, allowing you to use any cache system that implements the PSR-6 interface. If [Stash](https://github.com/decodelabs/stash) is installed, it will be used by default, otherwise:

```
$telegraph->cache = new MyPsrCachePool();
```

Usage
-----

[](#usage)

Once configured, Telegraph provides a simple API for interacting with your sources. Either load a specific source by name and operate on it directly, or use the shortcut methods on the main context to streamline common operations.

```
use DecodeLabs\Telegraph\MemberDataRequest;

$source = $telegraph->load('main');

$listInfo = $source->getListInfo();
echo $listInfo->name;

$request = new MemberDataRequest(
    email: 'test@example.com',
    firstName: 'Test',
    lastName: 'User',
    country: 'GB',
    language: 'en',
    groups: [
        '1234567890' => true,
    ],
    tags: [
        'test' => true,
    ]
);

$response = $source->subscribe($request);

if($response->success) {
    echo 'Subscription successful';
}
```

Or using the shortcut methods:

```
use DecodeLabs\Telegraph\MemberDataRequest;

$listInfo = $telegraph->getListInfo('main');
$request = new MemberDataRequest(...);
$response = $telegraph->subscribe('main', $request);
```

Fetch a subscribed member's information:

```
$memberInfo = $telegraph->getMemberInfo('main', 'test@example.com');

echo $memberInfo->email;
echo $memberInfo->firstName;
echo $memberInfo->lastName;
echo $memberInfo->country;
echo $memberInfo->language;

foreach($memberInfo->groups as $group) {
    echo $group->name;
}

foreach($memberInfo->tags as $tag) {
    echo $tag->name;
}
```

### Updating a member

[](#updating-a-member)

The `MemberDataRequest` class can also be used to update a member's data atomically:

```
use DecodeLabs\Telegraph\MemberDataRequest;

// Change name and email
$request = new MemberDataRequest(
    email: 'someone-else@example.com',
    firstName: 'Someone',
    lastName: 'Else',
);

$response = $telegraph->update('main', 'test@example.com', $request);
```

Groups and tags can be enabled or disabled by passing a boolean value with the group or tag key:

```
use DecodeLabs\Telegraph\MemberDataRequest;

$request = new MemberDataRequest(
    groups: [
        '1234567890' => false,
        '4567890123' => true,
    ],
    tags: [
        'test' => false,
        'new-tag' => true,
    ]
);

$response = $telegraph->update('main', 'someone-else@example.com', $request);
```

Unsubscribing a member just requires the email address:

```
$response = $telegraph->unsubscribe('main', 'someone-else@example.com');
```

User Stores
-----------

[](#user-stores)

When in heavy use, it is advisable to store the results of List and Member lookups in non-volatile storage to avoid piling up API requests when caches are cleared on application restart or deployment.

This only makes sense in the context of logged in users where non-volatile storage can be associated with a user account.

When using Telegraph in this way you should use the `*User()` methods instead of the regular methods - this will ensure that the results are stored against the user account and stores and caches are updated accordingly.

Take care not to mix the user and non-user oriented methods where possible - calls without a user ID can not affect the store so a mixed set of calls can leave the store out of sync. Generally, if an operation concerns a user with an account, you should operate with the user oriented methods.

You can provide a custom `Store` implementation to handle saving List and Member information to your database. See the [Store](./src/Telegraph/Store.php) interface for more details.

```
$telegraph->store = new MyStore();

$telegraph->subscribeUser(
    source: 'main',
    userId: '1234567890',
    request: new MemberDataRequest(
        email: 'test@example.com',
        firstName: 'Test',
        lastName: 'User',
    )
);

$telegraph->updateUser(
    source: 'main',
    userId: '1234567890',
    email: 'test@example.com',
    request: new MemberDataRequest(
        firstName: 'Another',
        lastName: 'User',
    )
);

$telegraph->unsubscribeUser(
    source: 'main',
    userId: '1234567890',
    email: 'test@example.com'
);

$info = $telegraph->getUserMemberInfo(
    source: 'main',
    userId: '1234567890',
    email: 'test@example.com'
);
```

Disciple
--------

[](#disciple)

Telegraph can be used in conjunction with the [Disciple](https://github.com/decodelabs/disciple) package to provide a seamless experience for subscribing users to mailing lists.

If `Disciple` is installed, the following methods can automatically fill in the member data request with the current user's data. Note, you will still need to provide a `MemberDataRequest` instance if you need to assign groups or tags.

```
$telegraph->subscribeDisciple();

$telegraph->updateDisciple(new MemberDataRequest(
    groups: [
        '1234567890' => true,
    ],
    tags: [
        'test' => true,
    ]
));

$telegraph->unsubscribeDisciple();
```

Commandment Actions
-------------------

[](#commandment-actions)

This package also provides a few useful CLI actions using the [Commandment](https://github.com/decodelabs/commandment) package.

Assuming you have [Effigy](https://github.com/decodelabs/effigy) installed plus the necessary dependencies for CLI commands, you can run the following commands in your project root:

```
# Refresh the cache for all sources
effigy telegraph/refresh

# Refresh the cache for a specific source
effigy telegraph/refresh mySource

# Show ListInfo for specified source
effigy telegraph/info mySource

# Show a list of all available lists on all connected services
effigy telegraph/probe
```

Licensing
---------

[](#licensing)

Telegraph is licensed under the MIT License. See [LICENSE](./LICENSE) for the full license text.

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance67

Regular maintenance activity

Popularity11

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity54

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 ~5 days

Recently: every ~16 days

Total

24

Last Release

227d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8a241d64d12b3b5ee94197862ec1ec30b82ed2efa34a0cd7f4c3565a021daddd?d=identicon)[betterthanclay](/maintainers/betterthanclay)

---

Top Contributors

[![betterthanclay](https://avatars.githubusercontent.com/u/1273586?v=4)](https://github.com/betterthanclay "betterthanclay (64 commits)")

### Embed Badge

![Health badge](/badges/decodelabs-telegraph/health.svg)

```
[![Health](https://phpackages.com/badges/decodelabs-telegraph/health.svg)](https://phpackages.com/packages/decodelabs-telegraph)
```

###  Alternatives

[webklex/php-imap

PHP IMAP client

4365.5M14](/packages/webklex-php-imap)[laravel-notification-channels/apn

Apple APN Push Notification Channel

2021.9M4](/packages/laravel-notification-channels-apn)[directorytree/imapengine

A fully-featured IMAP library -- without the PHP extension

531175.4k4](/packages/directorytree-imapengine)[meness/verifi

A Laravel package to handle email verification.

5516.9k](/packages/meness-verifi)[taiwan-sms/every8d

every8d sms api client

1817.8k](/packages/taiwan-sms-every8d)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)