List subscriptions
The newsletters and mailing lists the mailbox receives, as the Subscriptions page shows them.
Runs the real call on your workspace.
GET /subscriptions
The newsletters and mailing lists the mailbox receives, as the Subscriptions page shows them.
Example
Needs threads:read. A sender is a subscription when its mail carries a List-Unsubscribe header, with one row for each address it writes to. status is active, the default, kept or unsubscribed, q searches the sender, and sort is recent, most, emails, read, unread or name.
curl "$OE/subscriptions?sort=emails&limit=1" -H "$AUTH"{ "object": "list", "data": [{ "object": "subscription", "id": "sub_5d2c8e17", "senderEmail": "news@figma.com", "senderName": "Figma", "recipient": "hello@acme.com", "status": "active", "method": "one-click", "linkUrl": "https://www.figma.com/unsubscribe?u=4f1c", "unread": 12, "recent": 4, "total": 58, "readPercent": 79, "suggested": false, "sinceUnsubscribed": 0, "lastSeenAt": "2026-10-01T07:02:41.000Z", "unsubscribedAt": null, "unsubscribedWith": null, "future": null }], "total": 37, "counts": { "active": 37, "kept": 5, "unsubscribed": 9 }, "hasMore": true}recent counts the mail of the last 30 days, sinceUnsubscribed the mail that still arrived after you unsubscribed, and future names the rule that keeps moving its new mail, when there is one.
limit, 50 unless you say otherwise and at most 200, and offset page through them. total counts every row that matches, and counts how many are active, kept and unsubscribed.
A key or an app limited to particular addresses lists only the subscriptions delivered to them, and address narrows it to one address.
readPercent is the share of the sender's mail you read, from 0 to 100. suggested marks an active sender worth leaving: it can be unsubscribed, sent at least 5 emails, wrote in the last 30 days and has 10% or less of its mail read. suggested=true lists only those, and sort=read puts the least read first.
Google Workspace
Fastmail