Integrating RustMailer Unified Search API into Your CRM Application

✉️ RustMailer /unified-search API Introduction

🔍 API Purpose

The RustMailer /unified-search API enables rapid email searches within a local cache, supporting queries based on email address, time range, and account scope. This API avoids real-time IMAP server connections by leveraging a pre-built index table, making it ideal for integration with CRM systems, customer support platforms, or sales management tools.

🧠 Use Case Example: Retrieving Customer Email History in a CRM

In a CRM, you often need to:

• Display recent email interactions on a customer’s profile page.
• Quickly locate all communications for a customer across multiple email accounts.
• Filter emails by time range or communication direction (from/to).

The /unified-search API allows your CRM to retrieve emails from multiple accounts in a unified manner without dealing with underlying IMAP protocols, delivering millisecond-level response times.

🛠️ API Definition (OpenAPI)

POST /api/v1/unified-search

Request Parameters (Query):

Parameter	Type	Description
page	u64	Current page number (starts at 1)
page_size	u64	Number of emails per page
desc	bool	Sort by time in descending order (default: ascending)

Request Body (JSON):

{
  "email": "customer@example.com",
  "after": 1719859200000,
  "before": 1722451200000,
  "accounts": [1, 2, 5]
}

• email: Target email address, matches from/to/cc fields.
• after / before: Optional time range (UTC milliseconds).
• accounts: Optional list of email account IDs; if omitted, includes all accessible accounts.

✅ Example Request (curl)

curl -X POST https://your-server/api/v1/unified-search?page=1&page_size=50&desc=true \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "email": "alice@example.com",
        "after": 1720000000000,
        "before": 1720500000000
      }'

📦 Example Response (Simplified)

{
  "total": 12,
  "page": 1,
  "page_size": 50,
  "items": [
    {
      "account_id": 3127439432099413,
      "mailbox_id": 15004652606885140286,
      "mailbox_name": "INBOX",
      "uid": 241,
      "internal_date": 1752546329000,
      "size": 13427,
      "flags": [],
      "flags_hash": 0,
      "bcc": [],
      "cc": [],
      "date": 1752546326000,
      "from": {
        "name": "Google",
        "address": "no-reply@accounts.google.com"
      },
      "in_reply_to": null,
      "sender": null,
      "return_address": "3Frx1aAgTCa8cd-gTeanPRRdjcih.VddVaT.RdbedaanQPhTodWdbPXa.Rdb@identity-reachout.bounces.google.com",
      "message_id": "Iigig8Ybeha8HTsMwYTK6w@notifications.google.com",
      "subject": "Security alert for rustmailer.git@gmail.com",
      "thread_name": "Security alert for rustmailer.git@gmail.com",
      "mime_version": "1.0",
      "references": [],
      "reply_to": [],
      "to": [
        {
          "name": null,
          "address": "rustmailer.git@gmail.com"
        }
      ],
      "attachments": [],
      "body_meta": [
        {
          "id": "z7tjSOVqMHMg",
          "part_type": "Plain",
          "path": {
            "segments": [1]
          },
          "params": [
            {
              "key": "charset",
              "value": "UTF-8"
            },
            {
              "key": "delsp",
              "value": "yes"
            },
            {
              "key": "format",
              "value": "flowed"
            }
          ],
          "size": 1350,
          "transfer_encoding": "Base64"
        },
        {
          "id": "xIk8OtgQ0bbJ",
          "part_type": "Html",
          "path": {
            "segments": [2]
          },
          "params": [
            {
              "key": "charset",
              "value": "UTF-8"
            }
          ],
          "size": 6441,
          "transfer_encoding": "QuotedPrintable"
        }
      ],
      "received": {
        "from": null,
        "by": "mail-qv1-f72.google.com",
        "with": "SMTP",
        "date": 1752546327000
      }
    },
    ...
  ]
}

⚡ Performance Notes: Index-Based Fast Queries

The /unified-search API relies on RustMailer’s internal email index table, which stores metadata such as subjects, sender, recipient, and timestamps, without caching full email content or attachments during synchronization. This enables sub-second response times, even with millions of cached emails, supporting efficient paginated searches. The API returns a list of email metadata, allowing users to view a list of email subjects. When a user clicks to view an email’s content, RustMailer uses a separate API to fetch the email body and attachments from the IMAP server. These are cached on RustMailer’s local disk to avoid redundant IMAP fetches, with automatic cleanup to manage storage efficiently.

---

If you have any questions or need further assistance, feel free to reach out via GitHub Discussions or join our community on Discord. If you find RustMailer useful, give it a try and consider starring the project on GitHub!

---