Oui Incoming

Non défini

10 minute de lecture
A comprehensive RESTful API for managing incoming emails via IMAP. Features include email retrieval, voicemail parsing, automatic categorization, pattern detection
A comprehensive RESTful API for managing incoming emails via IMAP. Features include email retrieval, voicemail parsing, automatic categorization, pattern detection for helpdesk tickets, and webhook notifications.

A comprehensive RESTful API for managing incoming emails via IMAP. Features include email retrieval, voicemail parsing, automatic categorization, pattern detection for helpdesk tickets, and webhook notifications.

Base URL: https://incoming-api.oui.bzh

Overview

Base URL: https://incoming-api.oui.bzh
API Version: v1 (current)
Content-Type: application/json

Authentication

All API endpoints require authentication via API Key and Secret headers:

POST /api/auth/validate

Validates API key and secret, returns key information and permissions.

Response

{
  "success": true,
  "data": {
    "valid": true,
    "key": {
      "id": 1,
      "name": "Production Key",
      "permissions": ["read", "write", "send"],
      "rate_limit": {
        "requests_per_minute": 60,
        "requests_per_hour": 1000
      }
    }
  }
}
Security: API secrets are hashed and cannot be retrieved. Store your credentials securely. All connections must use HTTPS. Passwords are encrypted at rest using libsodium.

Emails

Endpoints for managing incoming emails retrieved via IMAP.

GET /api/emails

Parameters

ParameterTypeDescription
page integer Page number (default: 1)
per_page integer Items per page (default: 50, max: 100)
account_id integer Filter by mail account ID
folder string Filter by IMAP folder (e.g., INBOX, Sent)
from string Filter by sender email (partial match)
subject string Search in subject (partial match)
search string Full-text search in subject and body
has_attachments boolean Filter by attachment presence (0 or 1)
is_read boolean Filter by read status (0 or 1)
since date Emails received after (Y-m-d)
until date Emails received before (Y-m-d)
sort string Sort field: received_at, subject, from_address
order string Sort order: asc, desc (default: desc)

Parameters

ParameterTypeDescription
qRequired string Search query (min 2 characters)
limit integer Max results (default: 20, max: 50)

GET /api/emails/stats

Parameters

ParameterTypeDescription
account_id integer Filter by mail account ID

GET /api/emails/{id}

Returns full email content including body and attachments. Automatically marks the email as read.

Response

{
  "success": true,
  "data": {
    "id": 123,
    "account_id": 1,
    "message_uid": "12345",
    "message_id": "",
    "folder": "INBOX",
    "from_address": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
    "from_name": "John Doe",
    "to_addresses": [{"email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.", "name": "You"}],
    "cc_addresses": [],
    "reply_to": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
    "subject": "Important Email",
    "body_text": "Plain text content...",
    "body_html": "HTML content...",
    "headers": {"X-Priority": "1", "X-Mailer": "..."},
    "received_at": "2024-01-15T10:30:00Z",
    "read_at": "2024-01-15T10:35:00Z",
    "is_read": true,
    "is_starred": false,
    "is_archived": false,
    "has_attachments": true,
    "attachment_count": 2,
    "attachments": [
      {
        "id": 456,
        "filename": "document.pdf",
        "original_filename": "Invoice-2024.pdf",
        "mime_type": "application/pdf",
        "file_size": 125000,
        "is_inline": false,
        "content_id": null
      }
    ],
    "categories": [
      {"id": 1, "name": "Invoices", "slug": "invoices"}
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z"
  }
}

GET /api/emails/{id}/raw

Returns the raw text and HTML bodies with all headers.

Response

{
  "success": true,
  "data": {
    "id": 123,
    "subject": "Important Email",
    "body_text": "Full plain text...",
    "body_html": "Full HTML...",
    "headers": {
      "From": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
      "To": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
      "Date": "Mon, 15 Jan 2024 10:30:00 +0000",
      "Message-ID": "",
      "X-Mailer": "Mail Client",
      "Content-Type": "multipart/mixed"
    }
  }
}

PATCH /api/emails/{id}

Parameters

ParameterTypeDescription
is_read boolean Mark as read/unread
is_starred boolean Star/unstar email
is_archived boolean Archive/unarchive email
categories array Array of category IDs to assign

POST /api/emails/bulk

Parameters

ParameterTypeDescription
idsRequired array Array of email IDs
actionRequired string Action: mark_read, mark_unread, star, unstar, archive, unarchive, delete

DELETE /api/emails/{id}

Permanently deletes the email and its attachments.

Response

{
  "success": true,
  "message": "Email deleted"
}

Attachments

Endpoints for accessing email attachments. Attachments are stored outside the web root for security.

GET /api/emails/{id}/attachments

Response

{
  "success": true,
  "data": [
    {
      "id": 456,
      "filename": "document.pdf",
      "original_filename": "Invoice-2024.pdf",
      "mime_type": "application/pdf",
      "file_size": 125000,
      "is_inline": false,
      "content_id": null,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": 457,
      "filename": "image.png",
      "original_filename": "logo.png",
      "mime_type": "image/png",
      "file_size": 45000,
      "is_inline": true,
      "content_id": "logo123",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

GET /api/emails/{id}/attachments/{attachmentId}

Returns the raw attachment file with appropriate Content-Type and Content-Disposition headers.

GET /api/attachments/{id}

Response

{
  "success": true,
  "data": {
    "id": 456,
    "email_id": 123,
    "filename": "document.pdf",
    "original_filename": "Invoice-2024.pdf",
    "mime_type": "application/pdf",
    "file_size": 125000,
    "is_inline": false,
    "content_id": null,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

GET /api/attachments/{id}/download

Alternative endpoint for downloading attachments directly by ID.

Voicemails

Endpoints for managing voicemail notifications. The system automatically detects voicemail emails and extracts caller/receiver information.

GET /api/voicemails

Parameters

ParameterTypeDescription
page integer Page number (default: 1)
per_page integer Items per page (default: 50, max: 100)
account_id integer Filter by mail account
caller string Filter by caller number (partial match)
receiver string Filter by receiver line (partial match)
is_listened boolean Filter by listened status (0 or 1)
since date Voicemails after date (Y-m-d)
until date Voicemails before date (Y-m-d)
sort string Sort: received_at, caller_number, duration_seconds
order string Sort order: asc, desc

GET /api/voicemails/{id}

Response

{
  "success": true,
  "data": {
    "id": 45,
    "email_id": 123,
    "account_id": 1,
    "caller_number": "+33606473979",
    "caller_formatted": "06 06 47 39 79",
    "receiver_line": "33257578980",
    "duration_seconds": 42,
    "duration_formatted": "0:42",
    "has_audio": true,
    "is_listened": false,
    "listened_at": null,
    "received_at": "2024-01-15T10:30:00Z",
    "attachment_id": 789,
    "notes": null,
    "audio": {
      "attachment_id": 789,
      "filename": "voicemail_20240115.wav",
      "mime_type": "audio/wav",
      "file_size": 850000
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": null
  }
}

GET /api/voicemails/{id}/audio

Streams the voicemail audio file. Automatically converts GSM-encoded WAV files to MP3 for browser compatibility using ffmpeg.

Voicemail Detection: The system parses emails matching the pattern "Nouveau message en provenance de +33XXXXXXXXX sur votre ligne XXXXXXXXXX" to extract phone numbers and processes attached WAV files.
Auto-Conversion: WAV files with unsupported codecs (GSM, ADPCM, A-law, µ-law) are automatically converted to MP3 for browser playback.

Mail Accounts

Endpoints for managing IMAP mail accounts used to retrieve incoming emails.

GET /api/accounts

Parameters

ParameterTypeDescription
include_stats boolean Include email statistics (0 or 1)

POST /api/accounts

Parameters

ParameterTypeDescription
nameRequired string Account display name (2-100 chars)
emailRequired string Email address
hostRequired string IMAP server hostname
portRequired integer IMAP port (usually 993 for SSL)
usernameRequired string IMAP username
passwordRequired string IMAP password (encrypted at rest)
encryption string Encryption: ssl, tls, none (default: ssl)
is_active boolean Enable account (default: false)
sync_folders array Folders to sync (default: ["INBOX"])
test_connection boolean Test connection before saving

GET /api/accounts/{id}

Returns account configuration and email statistics.

PUT /api/accounts/{id}

Update account configuration. Password is only updated if provided.

POST /api/accounts/{id}/test

Response

{
  "success": true,
  "data": {
    "connected": true,
    "folders": ["INBOX", "Sent", "Drafts", "Trash", "Spam"],
    "message": "Connection successful"
  }
}

POST /api/accounts/{id}/sync

Parameters

ParameterTypeDescription
folder string Specific folder to sync
full_resync boolean Perform full resync
since_date date Resync emails since date (Y-m-d)

GET /api/accounts/{id}/folders

Response

{
  "success": true,
  "data": [
    {"name": "INBOX", "path": "INBOX", "messages": 1250, "unseen": 45},
    {"name": "Sent", "path": "Sent", "messages": 500, "unseen": 0},
    {"name": "Drafts", "path": "Drafts", "messages": 10, "unseen": 0},
    {"name": "Trash", "path": "Trash", "messages": 100, "unseen": 0}
  ]
}

GET /api/accounts/{id}/stats

Response

{
  "success": true,
  "data": {
    "total_emails": 1250,
    "unread_emails": 45,
    "with_attachments": 320,
    "by_folder": [
      {"folder": "INBOX", "count": 1000},
      {"folder": "Sent", "count": 200}
    ],
    "latest_email_at": "2024-01-15T10:30:00Z",
    "oldest_email_at": "2023-01-01T08:00:00Z"
  }
}

DELETE /api/accounts/{id}

Parameters

ParameterTypeDescription
delete_emails boolean Also delete all emails from this account

Categories

Endpoints for managing email categories and auto-categorization rules.

GET /api/categories

Parameters

ParameterTypeDescription
include_rules boolean Include category rules (0 or 1)
include_stats boolean Include email counts (0 or 1)
active_only boolean Only active categories (default: 1)

GET /api/categories/{id}

Returns category with rules and email count.

GET /api/categories/{id}/emails

Parameters

ParameterTypeDescription
page integer Page number (default: 1)
per_page integer Items per page (default: 50, max: 100)

Email Sending

Endpoints for sending transactional emails via Brevo integration.

POST /api/send

Thank you for signing up.

Parameters

ParameterTypeDescription
toRequired string|array Recipient(s) email address(es)
subjectRequired string Email subject (1-500 chars)
html string HTML content (required if no text)
text string Plain text content (required if no html)
from_email string Override sender email
from_name string Override sender name
reply_to string Reply-to address
cc string|array CC recipients
bcc string|array BCC recipients
attachments array Attachments [{name, content/url}]
tags array Tracking tags
config_id integer Specific send configuration to use

GET /api/send/status/{id}

Get the delivery status of a sent email by message ID or internal ID.

Response

{
  "success": true,
  "data": {
    "id": 123,
    "message_id": "",
    "status": "sent",
    "to": ["Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser."],
    "subject": "Welcome to Our Service",
    "sent_at": "2024-01-15T10:30:00Z",
    "error": null,
    "brevo_status": {
      "event": "delivered",
      "date": "2024-01-15T10:30:05Z"
    }
  }
}

GET /api/send/history

Parameters

ParameterTypeDescription
page integer Page number (default: 1)
per_page integer Items per page (default: 50, max: 100)
status string Filter: sent, failed
since date Emails sent after (Y-m-d)
until date Emails sent before (Y-m-d)

Pattern Detection

Endpoints for detecting helpdesk patterns, ticket IDs, and email threads.

POST /api/patterns/detect

Parameters

ParameterTypeDescription
email_idRequired integer Email ID to analyze

GET /api/patterns/rules

Response

{
  "success": true,
  "data": [
    {
      "key": "zendesk",
      "name": "Zendesk Ticket",
      "format": "#\\d{5,}"
    },
    {
      "key": "jira",
      "name": "Jira Issue",
      "format": "[A-Z]+-\\d+"
    },
    {
      "key": "freshdesk",
      "name": "Freshdesk Ticket",
      "format": "Ticket#\\d+"
    }
  ]
}

Webhooks

Register webhook endpoints to receive real-time notifications for email events.

GET /api/webhooks

Response

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "id": 1,
        "url": "https://your-app.com/webhook",
        "events": ["email.received", "voicemail.received"],
        "is_active": true,
        "trigger_count": 156,
        "last_triggered_at": "2024-01-15T10:30:00Z",
        "last_success_at": "2024-01-15T10:30:00Z",
        "last_failure_at": null,
        "consecutive_failures": 0
      }
    ],
    "supported_events": [
      "email.received",
      "email.categorized",
      "voicemail.received",
      "sync.completed",
      "sync.failed"
    ]
  }
}

POST /api/webhooks

Parameters

ParameterTypeDescription
urlRequired string Webhook endpoint URL (HTTPS)
eventsRequired array Events to subscribe to
secret string Signing secret for verification
is_active boolean Enable webhook (default: true)

PUT /api/webhooks/{id}

Update webhook URL, events, or active status.

POST /api/webhooks/{id}/test

Sends a test payload to verify your webhook endpoint.

Response

{
  "success": true,
  "data": {
    "message": "Test webhook delivered successfully",
    "http_code": 200,
    "response": "OK"
  }
}

DELETE /api/webhooks/{id}

Permanently removes the webhook subscription.

Data Models

Error Handling

All errors return consistent JSON responses with appropriate HTTP status codes.

{
  "success": false,
  "error": "Error message description"
}