IMAP and SMTP

Every Mailgentic inbox is also a standard IMAP account and SMTP submission endpoint. Point Thunderbird, Apple Mail, mutt, fetchmail, imaplib or any mail library at it — no SDK, no HTTP.

Clear-text login is refused before TLS on both protocols (LOGINDISABLED is advertised until STARTTLS completes).

Credentials

For an inbox (reading or sending as the agent): username is the inbox address, password is an API key — read scope for IMAP, send scope for SMTP. An inbox-scoped key is the natural choice: it can only touch that inbox.

For relay sending without an inbox: create a tenant SMTP credential (POST /v1/tenants/{id}/smtp-credentials) and use its username/password on smtp.mailgentic.ai.

IMAP

Folders map to IMAP mailboxes: INBOX, Sent, Drafts, Archive, Trash, Junk, plus any custom folder (nested with /). System names are case-insensitive.

• Each mailbox has its own stable, monotonic UID space and UIDVALIDITY.
• Flags round-trip with the API: \Seen ↔ read, \Answered, \Flagged, \Draft ↔ drafts. Labels appear as IMAP keywords; labels that are not valid keywords are preserved across STORE.
• COPY / MOVE are true copy/move with UIDPLUS COPYUID. APPEND (including to Drafts and Sent) returns APPENDUID.
• \Deleted + EXPUNGE permanently removes a message. The API’s own delete still goes to trash first.
• IDLE, NOOP and CHECK surface changes made by other sessions or by the API.
• Advertised capabilities: IMAP4rev1, IMAP4rev2, UIDPLUS, MOVE, SPECIAL-USE, LIST-EXTENDED, LIST-STATUS, NAMESPACE, IDLE, ESEARCH, SEARCHRES, BINARY, CHILDREN. Only verified capabilities are advertised.

import imaplib

im = imaplib.IMAP4_SSL("imap.mailgentic.ai", 993)
im.login("support@agents.mailgentic.ai", AGENT_KEY)   # inbox-scoped key
im.select("INBOX")
_, ids = im.search(None, "UNSEEN")
for uid in ids[0].split():
    _, data = im.fetch(uid, "(RFC822)")
    handle(data[0][1])
    im.store(uid, "+FLAGS", "\\Seen")

SMTP submission

import smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "support@agents.mailgentic.ai"     # must equal the inbox address
msg["To"] = "customer@example.net"
msg["Subject"] = "Re: I need help"
msg.set_content("Thanks — we're on it.")

with smtplib.SMTP("smtp.mailgentic.ai", 587) as s:
    s.starttls()
    s.login("support@agents.mailgentic.ai", AGENT_KEY)
    s.send_message(msg)

Rules that apply to SMTP submission from an inbox:

• MAIL FROM must equal the inbox address; anything else is rejected.
• The message runs through the same outbound policy as the API: DLP, recipient allowlist, hourly cap and approval holds. A held message is accepted by SMTP (250) and then appears as a pending approval; it is not silently dropped.
• Quotas, suppression list, DKIM signing, Guardian checks and events are identical to REST.
• If a pause with queue_action: reject covers the sender, submission is refused with 4.7.1.

Relay submissions with a tenant SMTP credential follow the same rules minus the inbox policy; the From domain must be registered and verified for the tenant.