List Entries

Authentication

Account API Key required via Authorization: Bearer {api_key} header.

Query Parameters

typestringquery

Filter by list type: allowlist or blocklist. Omit to see all types.

inbox_idstringquery

Filter by inbox UUID. Use "null" (as a string) to see only account-wide entries. Omit to see all entries.

# Get all list entries
curl -X GET https://api.daimon.email/v1/lists \
  -H "Authorization: Bearer dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o"

# Get only blocklist entries
curl -X GET 'https://api.daimon.email/v1/lists?type=blocklist' \
  -H "Authorization: Bearer dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o"

# Get entries for specific inbox
curl -X GET 'https://api.daimon.email/v1/lists?inbox_id=inb_abc123' \
  -H "Authorization: Bearer dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o"

# Get only account-wide entries
curl -X GET 'https://api.daimon.email/v1/lists?inbox_id=null' \
  -H "Authorization: Bearer dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o"

import { DaimonClient } from 'daimon-email';

const client = new DaimonClient({
  apiKey: 'dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o'
});

// Get all entries
const allLists = await client.lists.list();
console.log(`Total entries: ${allLists.total}`);

// Get only blocklist
const blocklist = await client.lists.list({ type: 'blocklist' });

// Get entries for specific inbox
const inboxLists = await client.lists.list({ inboxId: 'inb_abc123' });

// Get only account-wide entries
const accountWide = await client.lists.list({ inboxId: 'null' });

// Print all blocklisted domains
allLists.lists
  .filter(entry => entry.type === 'blocklist')
  .forEach(entry => {
    console.log(`Blocked: ${entry.address}`);
  });

from daimon_email import DaimonClient

client = DaimonClient(api_key='dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o')

# Get all entries
all_lists = client.lists.list()
print(f"Total entries: {all_lists.total}")

# Get only blocklist
blocklist = client.lists.list(type='blocklist')

# Get entries for specific inbox
inbox_lists = client.lists.list(inbox_id='inb_abc123')

# Get only account-wide entries
account_wide = client.lists.list(inbox_id='null')

# Print all blocklisted domains
for entry in all_lists.lists:
    if entry.type == 'blocklist':
        print(f"Blocked: {entry.address}")

Response

{
  "result": {
    "lists": [
      {
        "id": "lst_xyz789",
        "type": "blocklist",
        "address": "spam@example.com",
        "inbox_id": "inb_abc123",
        "inbox_address": "my-agent@daimon.email",
        "created_at": "2024-03-11T14:23:45Z"
      },
      {
        "id": "lst_abc456",
        "type": "blocklist",
        "address": "*@spammers.com",
        "inbox_id": null,
        "inbox_address": null,
        "created_at": "2024-03-10T09:15:22Z"
      },
      {
        "id": "lst_def123",
        "type": "allowlist",
        "address": "*@trusted.com",
        "inbox_id": "inb_abc123",
        "inbox_address": "my-agent@daimon.email",
        "created_at": "2024-03-09T16:30:00Z"
      }
    ],
    "total": 3
  },
  "next_steps": [
    "Use DELETE /v1/lists/{id} to remove entries",
    "Inbox-specific entries take precedence over account-wide entries",
    "Allowlist entries take precedence over blocklist entries"
  ]
}

Response Fields

listsarray

Array of list entry objects. Each entry contains:

id - Unique list entry identifier
type - allowlist or blocklist
address - Email address or wildcard pattern
inbox_id - Inbox UUID (null for account-wide)
inbox_address - Human-readable inbox address (null for account-wide)
created_at - ISO 8601 creation timestamp

totalnumber

Total number of list entries returned

Filtering Examples

View All Blocklists

const blocklists = await client.lists.list({ type: 'blocklist' });

blocklists.lists.forEach(entry => {
  const scope = entry.inbox_id ? `inbox ${entry.inbox_address}` : 'all inboxes';
  console.log(`${entry.address} blocked for ${scope}`);
});

Check Inbox-Specific Rules

const inboxRules = await client.lists.list({ inboxId: 'inb_abc123' });

const hasAllowlist = inboxRules.lists.some(e => e.type === 'allowlist');

if (hasAllowlist) {
  console.warn('This inbox uses an allowlist - only specific senders allowed');
}

Audit Account-Wide Rules

const accountWideRules = await client.lists.list({ inboxId: 'null' });

console.log(`Account-wide rules: ${accountWideRules.total}`);

accountWideRules.lists.forEach(entry => {
  console.log(`${entry.type}: ${entry.address}`);
});

Understanding Scope

List entries can be:

Account-wide (inbox_id: null) - Apply to all inboxes
Inbox-specific (inbox_id: "inb_...") - Apply to one inbox only

When checking if an email is allowed, the system evaluates:

Inbox-specific rules first
If no inbox-specific match, check account-wide rules
If no rules match, email is accepted (unless inbox has allowlist)

Example Flow

Incoming email: attacker@evil.com → my-agent@daimon.email (inb_abc123)

1. Check inbox-specific rules for inb_abc123
   - No match

2. Check account-wide rules
   - Match: "*@evil.com" on account-wide blocklist
   - Result: REJECT

Exporting Lists

// Export all blocklist entries to JSON
const blocklist = await client.lists.list({ type: 'blocklist' });

const exportData = blocklist.lists.map(entry => ({
  address: entry.address,
  scope: entry.inbox_id ? `inbox:${entry.inbox_address}` : 'account',
  created: entry.created_at
}));

console.log(JSON.stringify(exportData, null, 2));

Error Responses

401error

Invalid or missing API key

404error

Inbox not found (when filtering by inbox_id)

Info

Performance: List lookups are optimized with database indexing. Even with thousands of list entries, checks are performed in <10ms.

Warning

Allowlist caution: If you see any allowlist entries for an inbox, remember that only addresses on the allowlist can send to that inbox. All other addresses are implicitly blocked.

POST /v1/lists - Add a new list entry
DELETE /v1/lists/{id} - Remove a list entry

On this page