Esc

↑↓ move↵ openIndex · Pagefind
Email intake

Forward an email. Review a draft.

Each project can have inbound addresses. Mail sent to one becomes a draft RFI, a draft submittal or AP invoice documents, with the attachments, waiting for a person to review it. Without an address you can upload a saved .eml file through the app or the API.

PreviewDrafts only, never auto-approved.eml upload available now

What an email becomes

  • rfi
    An RFI in draft status: the subject becomes the RFI subject, the email text the question, and the attachments are attached to the question. It is created as the sender, so their RFI permissions apply.
  • submittal
    A submittal in Draft status with the email text in its description and the attachments on the submittal.
  • ap_invoice
    Each PDF or image attachment becomes a document in the company AP capture inbox, where a clerk codes and drafts the bill.

Project admins create, retarget, disable and rotate addresses under Project Admin > Email Intake or with the endpoints below. Rotating an address stops the old one immediately.

Receiving mail at inbound addresses is in preview and switched off until the inbound mail domain is set up; receiving_enabled on an address tells you whether mail is being received. Uploading an .eml works either way.

Create an addresscurl
curl -X POST https://app.os.construction/rest/v1.0/projects/{project_id}/email_intake/addresses \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "inbound_address": { "label": "Architect RFIs", "target_type": "rfi" } }'
# 201 { "id": 4, "address": "2001-harbor-view-k3f9x2m7q8w4@inbox.os.construction",
#       "target_type": "rfi", "enabled": true, "receiving_enabled": false, ... }

What is checked

  • Draft only
    Nothing is sent, opened, assigned, submitted, approved or posted. A person reviews every draft in the app.
  • Known senders
    Mail to an address is accepted only from an active member of the project (for AP invoices, also a vendor billing address mapped in AP automation).
  • Authenticated From
    The receiving provider must report DKIM or DMARC pass for the sender domain, so a forged From address is refused.
  • Automatic mail
    Auto-replies, out-of-office notices, list and bulk mail, bounces and mail loops are refused.
  • Limits
    25 MB per email, 20 MB and 10 files per draft by default, and a per-address hourly cap. Skipped files are listed on the log entry.
  • Once
    The same message (Message-ID) reaching the same address twice is processed once.
  • Audit
    Every email gets a log entry with its outcome and reason, an audit event and webhook events.
Upload an .emlcurl
curl -X POST "https://app.os.construction/rest/v1.0/projects/{project_id}/email_intake/messages?target_type=rfi" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@door-hardware.eml;type=message/rfc822"
# 201 { "id": 31, "status": "drafted", "target_type": "rfi",
#       "record": { "type": "rfi", "id": 212, "api_path": "/rest/v1.0/projects/2/rfis/212" }, ... }

Endpoints

Addresses and the log need the project Admin tool at admin level (admin:read, admin:write). An upload needs permission to create the target: rfis:write, submittals:write, or accounting:write with AP entry for invoices. Writes accept Idempotency-Key.

  • GET POST /projects/{project_id}/email_intake/addresses
    List or create addresses.
  • GET PATCH /projects/{project_id}/email_intake/addresses/{id}
    Show, relabel, retarget or enable/disable.
  • POST /projects/{project_id}/email_intake/addresses/{id}/rotate
    Issue a new address.
  • GET POST /projects/{project_id}/email_intake/messages
    The intake log (filter by status or address), or upload one .eml (multipart field file, query target_type).
  • GET /projects/{project_id}/email_intake/messages/{id}
    One log entry with its outcome, reason and draft link.

Webhook events

Subscribe to these like any webhook event. Payloads carry ids and outcomes only: no addresses, subjects or bodies.

  • inbound_email.received
    An email was logged for processing.
  • inbound_email.draft_created
    A draft was created. The draft also emits its own events, such as rfi.created.
  • inbound_email.rejected
    An email was refused, with a reason_code such as sender_unknown or auto_reply.
Eventjson
{
  "type": "inbound_email.draft_created",
  "data": { "address_id": 4, "source": "resend", "target_type": "rfi",
            "record_type": "rfi", "record_id": 212, "attachment_count": 2, "sender_verified": true }
}

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file