Get spam senders
/v1/spam/sendersorg.permission.spam.readorg.admin.spam.readThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Retrieves a paginated list of senders.
Spam senders
Spam senders are your org's allow and block lists for inbound email. Each entry is one email address marked `whitelist` (never treated as spam) or `blacklist` (always treated as spam), and it overrides Kustomer's automatic spam detection for that sender.
Kustomer checks inbound email for spam automatically. Detection isn't perfect, so each org keeps a list of senders whose mail should always or never be treated as spam. Admins edit the list in the admin settings or through this API, and spam detection can add entries itself, in which case automated is true and createdBy is null.
Key fields
| Field | Meaning |
|---|---|
sender |
The email address. Kustomer stores it lowercased and trimmed, the same way it compares inbound mail. |
channel |
Always email. |
list |
whitelist (never spam) or blacklist (always spam). |
automated |
true if spam detection added the entry rather than a person. |
deleted, deletedAt, deletedBy |
Set when the entry has been removed. |
When an entry is created, Kustomer links it to the customer with that email address, if there is one, so you can list a customer's entries with the customer filter.
One entry per address
There's only ever one entry per address, and removing it is a soft delete. Deleted entries drop out of lists unless you pass includeDeleted=true, but GET /v1/spam/senders/{id} still returns them with deleted: true. Because of this, the usual way to add or change a sender is the upsert, PUT /v1/spam/senders with sender, channel and list. It creates the entry with 201, or updates the existing one with 200, switching its list and restoring it if it was deleted.
Which endpoint to use
| To | Call |
|---|---|
| Allow or block a sender by email address | PUT /v1/spam/senders |
| Review the list, or one customer's entries | GET /v1/spam/senders, with customer or includeDeleted |
| Read one entry | GET /v1/spam/senders/{id} |
| Move an entry to the other list, or delete or restore it | PUT /v1/spam/senders/{id}, with list and/or deleted |
| Remove an entry | DELETE /v1/spam/senders/{id} |
A PUT /v1/spam/senders/{id} that doesn't change list or deleted returns the entry unchanged. If someone else changes the same entry at the same moment, a write can fail with 409 Conflict; read the entry again and retry. Reading and editing the list requires spam permissions, which are usually limited to admins.
Query parameters
Filter spam senders by customer ID.
"5f8efdd5d3de932f344ca367"Set to true to include deleted spam senders.
falseResponses
Success