Skip to content

Email

Block list and usage

Your block list stops email from being sent to addresses that cannot or do not want to receive it. Addresses that bounce permanently or mark your email as spam are added automatically.

List blocked addresses #

GET /v1/blocklist

Returns your blocked addresses and why each was added: bounce, complaint or manual.

Query parameters

limit integer
Results per page, 1–100. Default 20.
cursor string
The next_cursor from the previous page.
curl 
curl "https://api.maila.ai/v1/blocklist" \
  -H "Authorization: Bearer $MAILA_API_KEY"
Response 
{
  "object": "list",
  "data": [
    {
      "object": "blocked_address",
      "address": "old-address@example.com",
      "reason": "bounce",
      "source_item_id": "msg_mvdliiuwzfsa7ngv",
      "created_at": 1792335462
    }
  ],
  "next_cursor": null
}

Block an address #

POST /v1/blocklist

Adds an address. Email to it is refused until you remove it.

Body

address string required
The email address to block.
curl 
curl -X POST "https://api.maila.ai/v1/blocklist" \
  -H "Authorization: Bearer $MAILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "address": "jane@example.com" }'

Remove a blocked address #

DELETE /v1/blocklist/{address}

Removes an address so you can email it again. Write the @ as %40.

Path parameters

address string required
The blocked address.
curl 
curl -X DELETE "https://api.maila.ai/v1/blocklist/jane%40example.com" \
  -H "Authorization: Bearer $MAILA_API_KEY"

Get usage #

GET /v1/usage

Returns your plan, this month's requests and sent emails with their limits, and your forwarding counts. The counts reset on the first day of each month (UTC).

curl 
curl "https://api.maila.ai/v1/usage" \
  -H "Authorization: Bearer $MAILA_API_KEY"
Response 
{
  "object": "usage",
  "month": "2026-10",
  "request_count": 240,
  "request_limit": 1000,
  "sent_count": 12,
  "send_limit": 100,
  "tier": "Starter",
  "forwarded_count": 3,
  "forward_failed_count": 0,
  "forward_skipped_count": 1,
  "forward_verification_count": 1
}