Documentation / API Reference

Inbound Email

4 min read

The Inbound Email API lets you configure routing rules for incoming emails and access stored inbound messages.

Inbound Routes

Routes define how incoming emails are processed based on the recipient address.

List routes

Retrieve all inbound routing rules for your organization.

GET /v1/inbound/routes

Example request

curl https://api.mailingapi.com/v1/inbound/routes \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": [
    {
      "id": "ir_abc123",
      "name": "Support inbox",
      "match_type": "prefix",
      "pattern": "support@",
      "action": "store",
      "priority": 100,
      "status": "active",
      "matched_count": 1520,
      "last_matched_at": "2024-01-20T15:30:00Z",
      "created_at": "2024-01-10T10:00:00Z"
    }
  ]
}

Create route

Create a new inbound routing rule.

POST /v1/inbound/routes

Request body

Field Type Required Description
name string Yes Rule name (1-100 chars)
match_type string Yes Match type (see below)
pattern string * Match pattern (* required except for catchall)
action string Yes Action to take (see below)
action_config object Depends Action-specific configuration
priority integer No Priority 1-1000 (default: 100, lower = higher priority)
domain_id string No Restrict to specific domain
description string No Human-readable description
filters object No Additional filters
active boolean No Whether rule is active (default: true)

Match types

Type Description Pattern example
exact Exact email match support@example.com
prefix Matches start of address support@
suffix Matches end of address @support.example.com

| regex | Regular expression | ^(help|support)@.* | | catchall | Matches all emails | (no pattern needed) |

Actions

Action Description Required config
webhook POST message data to URL action_config.url
forward Forward to another email action_config.to
store Store for API retrieval (optional retention config)
drop Discard the message (none)

Action config examples

Webhook:

{
  "action_config": {
    "url": "https://yourapp.com/inbound-webhook",
    "secret": "optional-hmac-secret",
    "include_attachments": true
  }
}

Forward:

{
  "action_config": {
    "to": ["recipient@example.com"],
    "preserve_attachments": true
  }
}

Store:

{
  "action_config": {
    "retention_days": 7,
    "notify_url": "https://yourapp.com/notify",
    "notify_include_body": false
  }
}

Example request

curl -X POST https://api.mailingapi.com/v1/inbound/routes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support webhook",
    "match_type": "prefix",
    "pattern": "support@",
    "action": "webhook",
    "action_config": {
      "url": "https://yourapp.com/inbound",
      "include_attachments": true
    },
    "priority": 10
  }'

Response

{
  "id": "ir_new456",
  "name": "Support webhook",
  "match_type": "prefix",
  "pattern": "support@",
  "action": "webhook",
  "action_config": {
    "url": "https://yourapp.com/inbound",
    "include_attachments": true
  },
  "priority": 10,
  "status": "active",
  "created_at": "2024-01-20T16:00:00Z"
}

Get route

Retrieve details of a specific route.

GET /v1/inbound/routes/{route_id}

Example request

curl https://api.mailingapi.com/v1/inbound/routes/ir_abc123 \
  -H "Authorization: Bearer $API_KEY"

Update route

Update an existing routing rule.

PUT /v1/inbound/routes/{route_id}

Request body

Any of the fields from create (except organization_id).

Example request

curl -X PUT https://api.mailingapi.com/v1/inbound/routes/ir_abc123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": 5,
    "status": "paused"
  }'

Delete route

Delete an inbound routing rule.

DELETE /v1/inbound/routes/{route_id}

Example request

curl -X DELETE https://api.mailingapi.com/v1/inbound/routes/ir_abc123 \
  -H "Authorization: Bearer $API_KEY"

Response

204 No Content

Inbound Messages

Access stored inbound email messages (for routes with store action).

List messages

Retrieve stored inbound messages with filtering and pagination.

GET /v1/inbound/messages

Query parameters

Parameter Type Description
limit integer Results per page (default: 50, max: 100)
offset integer Number of results to skip
from string Filter by sender email (exact match)
to string Filter by recipient email (exact match)
since string Messages from this date (ISO 8601)
until string Messages until this date (ISO 8601)
domain_id string Filter by domain ID
is_spam boolean Filter by spam flag

Example request

curl "https://api.mailingapi.com/v1/inbound/messages?limit=25&since=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": [
    {
      "id": "im_abc123",
      "from": "sender@example.com",
      "to": ["support@yourdomain.com"],
      "subject": "Help with my order",
      "received_at": "2024-01-20T15:30:00Z",
      "spam_score": 1.2,
      "is_spam": false,
      "has_attachments": true
    }
  ],
  "meta": {
    "total": 150,
    "limit": 25,
    "offset": 0
  }
}

Get message

Retrieve full details of a stored inbound message.

GET /v1/inbound/messages/{message_id}

Example request

curl https://api.mailingapi.com/v1/inbound/messages/im_abc123 \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "id": "im_abc123",
  "from": "sender@example.com",
  "to": ["support@yourdomain.com"],
  "subject": "Help with my order",
  "html": "<p>I need help with order #12345...</p>",
  "text": "I need help with order #12345...",
  "headers": {
    "message-id": "<abc@example.com>",
    "date": "Mon, 20 Jan 2024 15:30:00 +0000"
  },
  "attachments": [
    {
      "filename": "screenshot.png",
      "content_type": "image/png",
      "size": 45230
    }
  ],
  "authentication": {
    "spf": "pass",
    "dkim": "pass",
    "dmarc": "pass"
  },
  "spam_score": 1.2,
  "is_spam": false,
  "thread_id": "thread_xyz",
  "received_at": "2024-01-20T15:30:00Z"
}

Get message thread

Retrieve all messages belonging to the same conversation thread.

GET /v1/inbound/messages/thread/{thread_id}

Example request

curl https://api.mailingapi.com/v1/inbound/messages/thread/thread_xyz \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": [
    {
      "id": "im_abc123",
      "from": "sender@example.com",
      "subject": "Help with my order",
      "received_at": "2024-01-20T15:30:00Z"
    },
    {
      "id": "im_def456",
      "from": "sender@example.com",
      "subject": "Re: Help with my order",
      "received_at": "2024-01-20T16:45:00Z"
    }
  ]
}

Download attachment

Get a presigned URL to download a message attachment. The URL is valid for 1 hour.

GET /v1/inbound/messages/{message_id}/attachments/{filename}

Example request

curl https://api.mailingapi.com/v1/inbound/messages/im_abc123/attachments/screenshot.png \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "url": "https://storage.example.com/attachments/...",
  "filename": "screenshot.png",
  "content_type": "image/png",
  "expires_at": "2024-01-20T16:30:00Z"
}

Delete message

Delete a stored inbound message and its attachments. This operation is irreversible.

DELETE /v1/inbound/messages/{message_id}

Example request

curl -X DELETE https://api.mailingapi.com/v1/inbound/messages/im_abc123 \
  -H "Authorization: Bearer $API_KEY"

Response

204 No Content

Error codes

Code Description
route_not_found Route ID not found
message_not_found Message ID not found
attachment_not_found Attachment not found
invalid_action Invalid action type
invalid_match_type Invalid match type
missing_action_config Required action config not provided
invalid_pattern Invalid regex pattern