Inbox API Documentation

Email receiving and processing API for automation workflows.

Quick Reference

Base URL:

https://api.ainoflow.io

Authentication:

Authorization: Bearer your_api_key_here

Core Concepts

Hook Address

• Globally unique email address per inbox
• Generated server-side with embedded HMAC signature
• Example: habcd1234-x7z8wq3m5n2kabcd@ainobox.com
• API operations use inbox GUID, not hook address

Sender Whitelisting

• Optional allowedFromEmails field
• Comma or semicolon delimited, normalized on save
• Case-insensitive, exact match only
• null = accept all senders

Message Lifecycle

• Received - email arrives, parsed, stored
• Handled - consumer calls /handle
• Expired - TTL reached, auto-deleted with files
• Deleted - manual removal via DELETE

TTL System

• ttlDays: Default 30 days, configurable per inbox
• Automatic cleanup: Messages + attachments deleted on expiry
• Deduplication: SHA-256 hash of raw email content
• isHandled: Processing flag, not retention flag

Main Endpoints

POST

Create Inbox

/api/v1/inbox

Create a new virtual email inbox. Returns the full inbox object with generated hook address.

Request Body:

name

required

- Human-readable label (max 100 chars)

allowedFromEmails

optional

- Sender whitelist, comma/semicolon delimited. null = accept all

webhookUrl

optional

- Push notification URL for new messages

ttlDays

optional

- Message retention in days (default: 30)

maxMessageSizeBytes

optional

- Max email size (default: 10MB)

maxAttachments

optional

- Max attachments per email (default: 10)

Response (201 Created):

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "hookAddress": "habcd1234-x7z8wq3m5n2kabcd@ainobox.com",
  "name": "Invoice intake",
  "allowedFromEmails": "partner@corp.com, alerts@service.com",
  "webhookUrl": "https://myapp.com/webhook/inbox",
  "ttlDays": 30,
  "enabled": true,
  "status": "active"
}

GET

List Messages

/api/v1/inbox/{id}/messages

Get paginated list of messages for an inbox. Primary endpoint for polling-based consumption. Returns full message content including body and attachment download URLs.

Query Parameters:

isHandled

optional

- Filter: true = handled only, false = unhandled only, omitted = all

limit

optional

- Items per page (default: 50, max: 5000)

page

optional

- Page number (1-based)

receivedAfter

optional

- Filter by receive date (ISO 8601)

fromAddress

optional

- Filter by sender (case-insensitive contains)

sortBy

optional

- ReceivedAt (default), FromAddress, Subject, SizeBytes

Response (200 OK):

{
  "items": [{
    "id": "7fa85f64-...",
    "fromAddress": "sender@example.com",
    "subject": "Invoice #12345",
    "bodyText": "Please find attached...",
    "isHandled": false,
    "hasAttachments": true,
    "attachments": [{
      "id": "9fa85f64-...",
      "fileName": "invoice.pdf",
      "downloadUrl": "https://..."
    }]
  }],
  "totalCount": 42
}

POST

Handle Message

/api/v1/inbox/{id}/messages/{messageId}/handle

Returns full message content AND marks as handled in one atomic operation. Idempotent - repeated calls return success.

Path Parameters:

id

required

- Inbox ID (GUID)

messageId

required

- Message ID (GUID)

Response (200 OK):

Full message with body, attachments, and download URLs. isHandled: true.

POST

Batch Handle Messages

/api/v1/inbox/{id}/messages/handle

Handle multiple messages in one call. Provide specific IDs or handle first N unhandled messages (default: 10, max: 100).

Request Body:

messageIds

optional

- Specific message IDs to handle. If null/empty, handles first N unhandled

limit

optional

- Max messages to handle when messageIds not provided (default: 10, max: 100)

PUT

Update Inbox

/api/v1/inbox/{id}

Update inbox configuration. Only provided fields are updated.

Request Body:

name

optional

- Updated label

allowedFromEmails

optional

- Updated sender whitelist. null to remove filter

webhookUrl

optional

- Updated webhook URL. null to remove

ttlDays

optional

- Updated retention period

enabled

optional

- Enable or disable the inbox

DELETE

Delete Inbox

/api/v1/inbox/{id}

Delete an inbox and all its messages and attachments. Cascading delete - all associated data permanently removed.

Response (200 OK):

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "hookAddress": "habcd1234-x7z8wq3m5n2kabcd@ainobox.com"
}

DELETE

Delete Message

/api/v1/inbox/{id}/messages/{messageId}

Delete a single message and all its attachments from both database and storage.

Response (200 OK):

{
  "id": "7fa85f64-5717-4562-b3fc-2c963f66afa6"
}

GET

Get Attachment Download URL

/api/v1/inbox/{id}/messages/{messageId}/attachments/{attachmentId}/url

Get a pre-signed URL for direct attachment download. Use when your HTTP client doesn't follow redirects.

Query Parameters:

expirySeconds

optional

- URL expiration time in seconds (default: 3600, min: 60, max: 86400)

Response (200 OK):

{
  "downloadUrl": "https://storage.example.com/inbox/...?signature=...",
  "downloadUrlExpiresAt": "2026-02-20T11:30:00Z"
}

Example Usage

cURL Examples

Create inbox

curl -X POST "https://api.ainoflow.io/api/v1/inbox" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Invoice intake", "ttlDays": 30}'

Poll for unhandled messages

curl "https://api.ainoflow.io/api/v1/inbox/{id}/messages?isHandled=false&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Handle a message

curl -X POST "https://api.ainoflow.io/api/v1/inbox/{id}/messages/{messageId}/handle" \
  -H "Authorization: Bearer YOUR_API_KEY"

Batch handle unhandled messages

curl -X POST "https://api.ainoflow.io/api/v1/inbox/{id}/messages/handle" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 10}'

Delete inbox

curl -X DELETE "https://api.ainoflow.io/api/v1/inbox/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

n8n / Make.com Integration

Polling Workflow Pattern

Process incoming emails with a simple polling pattern

1. Schedule Trigger (every 5 min):
   → Start polling cycle

2. HTTP Request Node:
   GET /api/v1/inbox/{id}/messages?isHandled=false&limit=10
   → Returns unhandled messages with full content

3. Loop / Split In Batches:
   → Process each message

4. For each message:
   → Extract body text, attachments
   → Download attachments via downloadUrl
   → Run business logic (OCR, routing, etc.)

5. HTTP Request Node (after processing):
   POST /api/v1/inbox/{id}/messages/{messageId}/handle
   → Mark as handled

HTTP Status Codes

200

OK - Request successful (list, get, update, delete, handle)

201

Created - Inbox created successfully

400

Bad Request - Invalid parameters, missing required fields, blocked webhook URL

401

Unauthorized - Missing or invalid API key

404

Not Found - Inbox, message, or attachment not found in current scope/project

429

Too Many Requests - Max inboxes per scope reached

500

Internal Server Error - Server error

Best Practices

Polling Strategy

• Poll every 1-5 minutes for most use cases
• Use isHandled=false filter
• Handle messages after processing

Webhook Usage

• Use webhooks for real-time processing
• Fetch full content via API after webhook
• Webhook delivery is non-blocking

Attachment Handling

• Download URLs included in list/handle responses
• URLs expire in 1 hour by default
• Use /url endpoint for fresh URLs

Sender Whitelisting

• Restrict senders for production inboxes
• Non-whitelisted emails silently rejected
• Set to null to accept all senders

Ready to Get Started?

Create your free account and start receiving emails in your workflows in minutes.

Get API Key Learn More