Allow/Block Lists

Allow/block lists (also called filter rules) let you control which email addresses and domains can interact with your inboxes. They act as gatekeepers for both sending and receiving email.

Concepts

Filter rules operate on two axes:

Axis	Options	Description
Direction	`send` or `receive`	Whether the rule applies to outbound or inbound email
Action	`allow` or `block`	Whether to permit or deny the address/domain

Match types:

Type	Example	Matches
`address`	`spam@example.com`	Only that exact address
`domain`	`example.com`	Any address at that domain
`subdomain_wildcard`	`*.example.com`	Any address at any subdomain of example.com

Creating filter rules

// Block all email from a specific domain
await client.filterRules.create({
  direction: 'receive',
  action: 'block',
  match_type: 'domain',
  value: 'spam-company.com',
});

// Allow sending only to a specific partner domain
await client.filterRules.create({
  direction: 'send',
  action: 'allow',
  match_type: 'domain',
  value: 'trusted-partner.com',
});

// Block a specific sender
await client.filterRules.create({
  direction: 'receive',
  action: 'block',
  match_type: 'address',
  value: 'harasser@example.com',
});

# Block all email from a specific domain
client.filter_rules.create(
    direction="receive",
    action="block",
    match_type="domain",
    value="spam-company.com",
)

# Allow sending only to a trusted partner
client.filter_rules.create(
    direction="send",
    action="allow",
    match_type="domain",
    value="trusted-partner.com",
)

# Block all email from a domain
curl -X POST https://api.agent-post.dev/api/v1/filter-rules \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "receive",
    "action": "block",
    "match_type": "domain",
    "value": "spam-company.com"
  }'

Most-specific-wins evaluation

When multiple rules could apply to an address, the most specific rule wins:

address  >  domain  >  subdomain_wildcard

Example: If you have:

Block *.example.com (subdomain wildcard)
Allow support.example.com (domain)
Block spam@support.example.com (address)

Then:

user@marketing.example.com -- blocked (matched by *.example.com)
user@support.example.com -- allowed (domain rule is more specific than wildcard)
spam@support.example.com -- blocked (address rule is most specific)

Send-block behavior

When a send-block rule matches, the entire send operation is rejected with a 422 status code. There are no partial sends -- if any recipient is blocked, the whole message is rejected.

try {
  await client.messages.send('inb_abc123', {
    to: [
      { email: 'allowed@partner.com' },
      { email: 'blocked@competitor.com' },
    ],
    subject: 'Proposal',
    text_body: 'Please review the attached proposal.',
  });
} catch (error) {
  // 422: Send blocked -- blocked_recipients detail includes competitor.com
  console.error(error.message);
}

try:
    client.messages.send(
        inbox_id="inb_abc123",
        to=[
            {"email": "allowed@partner.com"},
            {"email": "blocked@competitor.com"},
        ],
        subject="Proposal",
        text_body="Please review the attached proposal.",
    )
except Exception as error:
    # 422: Send blocked -- blocked_recipients detail includes competitor.com
    print(error)

# This will return 422 if any recipient is blocked
curl -X POST https://api.agent-post.dev/api/v1/inboxes/inb_abc123/messages \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{"email": "blocked@competitor.com"}],
    "subject": "Proposal",
    "text_body": "Please review."
  }'

Receive-block behavior

When a receive-block rule matches an inbound message, the message is silently discarded. An audit log entry is created for the blocked delivery, but no bounce response is sent to the sender.

Bulk operations

Create or delete multiple filter rules at once:

await client.filterRules.bulkCreate({
  rules: [
    { direction: 'receive', action: 'block', match_type: 'domain', value: 'spammer1.com' },
    { direction: 'receive', action: 'block', match_type: 'domain', value: 'spammer2.com' },
    { direction: 'receive', action: 'block', match_type: 'domain', value: 'spammer3.com' },
  ],
});

client.filter_rules.bulk_create(
    rules=[
        {"direction": "receive", "action": "block", "match_type": "domain", "value": "spammer1.com"},
        {"direction": "receive", "action": "block", "match_type": "domain", "value": "spammer2.com"},
        {"direction": "receive", "action": "block", "match_type": "domain", "value": "spammer3.com"},
    ],
)

curl -X POST https://api.agent-post.dev/api/v1/filter-rules/bulk \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {"direction": "receive", "action": "block", "match_type": "domain", "value": "spammer1.com"},
      {"direction": "receive", "action": "block", "match_type": "domain", "value": "spammer2.com"},
      {"direction": "receive", "action": "block", "match_type": "domain", "value": "spammer3.com"}
    ]
  }'

Listing filter rules

const rules = await client.filterRules.list({
  direction: 'receive',
  action: 'block',
});

for (const rule of rules.data) {
  console.log(`${rule.action} ${rule.match_type}: ${rule.value} (${rule.direction})`);
}

rules = client.filter_rules.list(direction="receive", action="block")

for rule in rules.data:
    print(f"{rule.action} {rule.match_type}: {rule.value} ({rule.direction})")

curl "https://api.agent-post.dev/api/v1/filter-rules?direction=receive&action=block" \
  -H "Authorization: Bearer $AGENTPOST_API_KEY"

Tips

Filter rules are organization-wide -- they apply to all inboxes in the organization
Use send-block rules to prevent your agents from accidentally emailing sensitive domains
Receive-block rules are evaluated before message storage, saving storage space
The most-specific-wins logic means you can block a domain but allow specific addresses within it
Filter rules are checked in real time -- changes take effect immediately

Allow/Block Lists

On this page