Create List Entry

Authentication

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

Overview

Lists control which email addresses can send to your inboxes:

Allowlist: Only addresses on this list can send (rejects all others)
Blocklist: Addresses on this list are rejected (allows all others)

Lists can be account-wide (apply to all inboxes) or scoped to specific inboxes.

Request Body

typestringbodyrequired

List type: allowlist or blocklist

addressstringbodyrequired

Email address to add. Supports exact addresses (user@example.com) and wildcard domains (*@example.com).

inbox_idstring | nullbody

Optional inbox UUID. If provided, list entry only applies to this inbox. If null/omitted, applies to all inboxes in the account.

curl -X POST https://api.daimon.email/v1/lists \
  -H "Authorization: Bearer dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "blocklist",
    "address": "spam@example.com",
    "inbox_id": "inb_abc123"
  }'

import { DaimonClient } from 'daimon-email';

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

// Block specific address for one inbox
const entry = await client.lists.create({
  type: 'blocklist',
  address: 'spam@example.com',
  inboxId: 'inb_abc123'
});

// Block entire domain account-wide
const domainBlock = await client.lists.create({
  type: 'blocklist',
  address: '*@spammers.com',
  inboxId: null  // Account-wide
});

// Allowlist - only accept from specific domain
const allowlist = await client.lists.create({
  type: 'allowlist',
  address: '*@trusted.com',
  inboxId: 'inb_abc123'
});

from daimon_email import DaimonClient

client = DaimonClient(api_key='dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o')

# Block specific address for one inbox
entry = client.lists.create(
    type='blocklist',
    address='spam@example.com',
    inbox_id='inb_abc123'
)

# Block entire domain account-wide
domain_block = client.lists.create(
    type='blocklist',
    address='*@spammers.com',
    inbox_id=None  # Account-wide
)

# Allowlist - only accept from specific domain
allowlist = client.lists.create(
    type='allowlist',
    address='*@trusted.com',
    inbox_id='inb_abc123'
)

Response

{
  "result": {
    "id": "lst_xyz789",
    "type": "blocklist",
    "address": "spam@example.com",
    "inbox_id": "inb_abc123",
    "created_at": "2024-03-11T14:23:45Z"
  },
  "next_steps": [
    "Emails from spam@example.com will now be rejected for inbox inb_abc123",
    "Use GET /v1/lists to view all list entries",
    "Use DELETE /v1/lists/{id} to remove this entry"
  ]
}

Response Fields

idstring

Unique list entry identifier (prefix: lst_)

typestring

List type: allowlist or blocklist

addressstring

Email address or wildcard pattern

inbox_idstring | null

Inbox this entry is scoped to, or null for account-wide

created_atstring

ISO 8601 timestamp of entry creation

Address Patterns

Exact Address

await client.lists.create({
  type: 'blocklist',
  address: 'user@example.com'
});
// Blocks only user@example.com

Wildcard Domain

await client.lists.create({
  type: 'blocklist',
  address: '*@example.com'
});
// Blocks all addresses @example.com

Subdomain Wildcard

await client.lists.create({
  type: 'allowlist',
  address: '*@*.company.com'
});
// Allows email@team.company.com, support@dev.company.com, etc.

List Precedence

When multiple list entries match an incoming email:

Inbox-specific rules take precedence over account-wide rules
Allowlist takes precedence over blocklist
Exact matches take precedence over wildcards

Example

// Account-wide: block all @example.com
await client.lists.create({
  type: 'blocklist',
  address: '*@example.com',
  inboxId: null
});

// Inbox-specific: allow admin@example.com
await client.lists.create({
  type: 'allowlist',
  address: 'admin@example.com',
  inboxId: 'inb_abc123'
});

// Result:
// - admin@example.com → allowed (inbox-specific allowlist wins)
// - other@example.com → blocked (account-wide blocklist)

Use Cases

Spam Protection

// Block known spam domains
await client.lists.create({
  type: 'blocklist',
  address: '*@spam-domain.com'
});

Restricted Inbox

// Only accept from company email
await client.lists.create({
  type: 'allowlist',
  address: '*@mycompany.com',
  inboxId: 'inb_internal'
});

Temporary Block

// Block abusive sender
const block = await client.lists.create({
  type: 'blocklist',
  address: 'abusive@example.com'
});

// Later: unblock
await client.lists.delete(block.id);

Error Responses

400error

Invalid request - invalid email format or invalid list type

401error

Invalid or missing API key

404error

Inbox not found or does not belong to this account

409error

Entry already exists (same type, address, and inbox_id combination)

Warning

Allowlist behavior: When you add an allowlist entry to an inbox, all other addresses are automatically blocked for that inbox. Only use allowlists when you want strict sender restrictions.

Info

Wildcard performance: Wildcard patterns are evaluated efficiently. There's no performance penalty for using *@domain.com over exact addresses.

GET /v1/lists - View all list entries
DELETE /v1/lists/{id} - Remove a list entry

On this page