Email Ingestion and Delivery
The email ingestion and delivery feature defines how signed-in users with saved credentials sync inbound email and queue outbound sends. It gives you one clear order of use: sign in, set credentials, then run IMAP and SMTP operations.
Why This Matters
This feature stores provider email data in a consistent account shape so reads and writes stay predictable across IMAP and SMTP flows. It separates metadata search from full body and part retrieval, and it ties provider actions to tasks and jobs for clear retry behavior.
Core Flow
After sign in, the client uses saved credentials to sync mailboxes or messages from IMAP. Inbox Manager stores message and part data, clients search and read what they need, and outbound SMTP sends are queued while results are tracked through tasks, jobs, and logs.
Operations
| Operation | Endpoint | Purpose |
|---|---|---|
| Sync mailboxes | POST /api/accounts/:account_id/imap/sync-mailboxes | Enqueue mailbox synchronization |
| Sync messages | POST /api/accounts/:account_id/imap/sync-messages | Enqueue message synchronization |
| Send SMTP message | POST /api/accounts/:account_id/smtp/messages | Enqueue outbound message send |
| List emails | GET /api/accounts/:account_id/emails | List account email metadata |
| Search emails | POST /api/accounts/:account_id/emails/search | Query emails by indexed fields |
| Delete emails by search | POST /api/accounts/:account_id/emails/search-delete | Bulk delete matched email records |
| Create email record | POST /api/accounts/:account_id/emails | Create email record explicitly |
| Get email | GET /api/emails/:email_id | Retrieve one email record |
| Update email | PATCH /api/emails/:email_id | Update mutable email fields |
| Delete email | DELETE /api/emails/:email_id | Delete one email record |
| Get full body | GET /api/accounts/:account_id/emails/:email_id/body | Retrieve parsed message body |
| List parts | GET /api/accounts/:account_id/emails/:email_id/parts | Retrieve message part metadata |
| Get part content | GET /api/accounts/:account_id/emails/:email_id/parts/:part_id/content | Retrieve decoded content for one part |
Key Data and State
| Item | Purpose | Linked To |
|---|---|---|
email_message | Stored inbound/outbound message data | task, job, provider credential |
email_message_part | Part data for attachments and embeds | email_message |
email_message_part_content | Decoded part payload | email_message_part |
task | Requested provider operation | job |
Failure Modes and Controls
Provider sync or send failures are surfaced through task/job state and audit trails rather than silent drops. Account-scoped routes reject account mismatches, search-delete remains explicit and scoped, and body or part-content retrieval stays on dedicated endpoints to prevent accidental over-fetch during list or search operations.
Related
Email Message, Email Message Part, Email Message Part Content, Task, IMAP Sync Guide, Search and Read Guide, Send Outbound Email Guide.