Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Core Tools

Email Intake

8 endpoints8 implementedAll modules →
  1. GET /rest/v1.0/projects/{project_id}/email_intake/addressesList inbound email addresses
  2. POST /rest/v1.0/projects/{project_id}/email_intake/addressesCreate an inbound email address
  3. GET /rest/v1.0/projects/{project_id}/email_intake/addresses/{id}Show an inbound email address
  4. PATCH /rest/v1.0/projects/{project_id}/email_intake/addresses/{id}Update an inbound email address
  5. POST /rest/v1.0/projects/{project_id}/email_intake/addresses/{id}/rotateRotate an inbound email address
  6. GET /rest/v1.0/projects/{project_id}/email_intake/messagesList the email intake log
  7. POST /rest/v1.0/projects/{project_id}/email_intake/messagesUpload an .eml as a draft
  8. GET /rest/v1.0/projects/{project_id}/email_intake/messages/{id}Show an email intake log entry
GET /rest/v1.0/projects/{project_id}/email_intake/addresses

List inbound email addresses

Requires the project Admin tool at admin level (token scope admin:read for reads, admin:write for writes).

v1.0Implemented

Parameters

  • OS-Company-Id
    integerheaderrequired
  • project_id
    integerpathrequired

Response · 200 · object[]

  • id
    integerrequired
  • project_id
    integerrequired
  • address
    stringrequired
    The full inbound address, <slug>-<token>@<inbound domain>.
  • label
    string | null
  • target_type
    stringrequired
    One of: rfi, submittal, ap_invoice.
  • enabled
    booleanrequired
  • receiving_enabled
    booleanrequired
    Whether the platform currently receives mail (INBOUND_EMAIL_ENABLED). Uploading .eml works either way.
  • created_by_id
    integer
  • rotated_at
    string (date-time) | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 403Not a project admin

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/email_intake/addresses" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/projects/{project_id}/email_intake/addresses

Create an inbound email address

Requires the project Admin tool at admin level (token scope admin:read for reads, admin:write for writes).

v1.0Implemented

Parameters

  • OS-Company-Id
    integerheaderrequired
  • project_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • inbound_address
    objectrequired
  • inbound_address.label
    string | null
  • inbound_address.target_type
    string
    One of: rfi, submittal, ap_invoice.

Response · 201 · object

  • id
    integerrequired
  • project_id
    integerrequired
  • address
    stringrequired
    The full inbound address, <slug>-<token>@<inbound domain>.
  • label
    string | null
  • target_type
    stringrequired
    One of: rfi, submittal, ap_invoice.
  • enabled
    booleanrequired
  • receiving_enabled
    booleanrequired
    Whether the platform currently receives mail (INBOUND_EMAIL_ENABLED). Uploading .eml works either way.
  • created_by_id
    integer
  • rotated_at
    string (date-time) | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 403Not a project admin
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/email_intake/addresses" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "inbound_address": {}
}'
GET /rest/v1.0/projects/{project_id}/email_intake/addresses/{id}

Show an inbound email address

Requires the project Admin tool at admin level (token scope admin:read for reads, admin:write for writes).

v1.0Implemented

Parameters

  • OS-Company-Id
    integerheaderrequired
  • project_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • project_id
    integerrequired
  • address
    stringrequired
    The full inbound address, <slug>-<token>@<inbound domain>.
  • label
    string | null
  • target_type
    stringrequired
    One of: rfi, submittal, ap_invoice.
  • enabled
    booleanrequired
  • receiving_enabled
    booleanrequired
    Whether the platform currently receives mail (INBOUND_EMAIL_ENABLED). Uploading .eml works either way.
  • created_by_id
    integer
  • rotated_at
    string (date-time) | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 404Not found

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/email_intake/addresses/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/projects/{project_id}/email_intake/addresses/{id}

Update an inbound email address

Requires the project Admin tool at admin level (token scope admin:read for reads, admin:write for writes). Disable an address to stop it accepting mail; mail to a disabled address is logged as rejected.

v1.0Implemented

Parameters

  • OS-Company-Id
    integerheaderrequired
  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • inbound_address
    objectrequired
  • inbound_address.label
    string | null
  • inbound_address.target_type
    string
    One of: rfi, submittal, ap_invoice.
  • inbound_address.enabled
    boolean

Response · 200 · object

  • id
    integerrequired
  • project_id
    integerrequired
  • address
    stringrequired
    The full inbound address, <slug>-<token>@<inbound domain>.
  • label
    string | null
  • target_type
    stringrequired
    One of: rfi, submittal, ap_invoice.
  • enabled
    booleanrequired
  • receiving_enabled
    booleanrequired
    Whether the platform currently receives mail (INBOUND_EMAIL_ENABLED). Uploading .eml works either way.
  • created_by_id
    integer
  • rotated_at
    string (date-time) | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 404Not found
  • 422Invalid body

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/projects/1/email_intake/addresses/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "inbound_address": {}
}'
POST /rest/v1.0/projects/{project_id}/email_intake/addresses/{id}/rotate

Rotate an inbound email address

Requires the project Admin tool at admin level (token scope admin:read for reads, admin:write for writes). Issues a new unguessable address; the previous one stops accepting mail immediately.

v1.0Implemented

Parameters

  • OS-Company-Id
    integerheaderrequired
  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Response · 200 · object

  • id
    integerrequired
  • project_id
    integerrequired
  • address
    stringrequired
    The full inbound address, <slug>-<token>@<inbound domain>.
  • label
    string | null
  • target_type
    stringrequired
    One of: rfi, submittal, ap_invoice.
  • enabled
    booleanrequired
  • receiving_enabled
    booleanrequired
    Whether the platform currently receives mail (INBOUND_EMAIL_ENABLED). Uploading .eml works either way.
  • created_by_id
    integer
  • rotated_at
    string (date-time) | null
  • created_at
    string (date-time)
  • updated_at
    string (date-time)

Errors

  • 404Not found

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/email_intake/addresses/1/rotate" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/projects/{project_id}/email_intake/messages

List the email intake log

Requires the project Admin tool at admin level (token scope admin:read for reads, admin:write for writes). Newest first. Bodies are not stored in the log; open the draft record.

v1.0Implemented

Parameters

  • OS-Company-Id
    integerheaderrequired
  • project_id
    integerpathrequired
  • status
    stringquery
    One of: received, drafted, rejected, failed.
  • address_id
    integerquery
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    integerrequired
  • project_id
    integerrequired
  • address_id
    integer | null
  • source
    stringrequired
    One of: resend, eml_upload.
  • status
    stringrequired
    One of: received, drafted, rejected, failed.
  • reason_code
    string | null
    auto_reply, bulk_mail, mail_loop, bounce_sender, sender_unauthenticated, sender_unknown, sender_not_permitted, too_large, rate_limited, address_disabled, unparseable, no_sender, processing_failed
  • reason
    string | null
  • target_type
    stringrequired
    One of: rfi, submittal, ap_invoice.
  • from_address
    string
  • sender_user_id
    integer | null
  • sender_verified
    boolean
  • subject
    string | null
  • size_bytes
    integer
  • attachment_count
    integer
  • skipped_attachments
    object[]
  • skipped_attachments[].filename
    string
  • skipped_attachments[].reason
    string
  • authentication
    object | null
  • authentication.spf
    string | null
  • authentication.dkim
    string | null
  • authentication.dmarc
    string | null
  • record
    object | null
  • record.type
    string
    One of: rfi, submittal, ap_captured_document.
  • record.id
    integer | null
  • record.api_path
    string | null
  • uploaded_by_id
    integer | null
  • received_at
    string (date-time)
  • processed_at
    string (date-time) | null
  • created_at
    string (date-time)

Errors

  • 403Not a project admin

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/email_intake/messages" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/projects/{project_id}/email_intake/messages

Upload an .eml as a draft

Uploads one RFC 5322 message (.eml) and turns it into a DRAFT for review, created as the caller. target_type rfi needs RFI create permission (rfis:write), submittal needs submittal create permission (submittals:write), ap_invoice needs AP entry (accounting:write) and puts the PDF/image attachments in the AP capture inbox. Auto-replies, list mail and loops are rejected. A repeat upload of the same message (same Message-ID) answers 200 with the earlier log entry. Works whether or not inbound mail receiving is enabled.

v1.0Implemented

Parameters

  • OS-Company-Id
    integerheaderrequired
  • project_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
  • target_type
    stringquery
    One of: rfi, submittal, ap_invoice.

Request body

  • file
    string (binary)required
    The .eml file (message/rfc822).

Response · 200 · object

  • id
    integerrequired
  • project_id
    integerrequired
  • address_id
    integer | null
  • source
    stringrequired
    One of: resend, eml_upload.
  • status
    stringrequired
    One of: received, drafted, rejected, failed.
  • reason_code
    string | null
    auto_reply, bulk_mail, mail_loop, bounce_sender, sender_unauthenticated, sender_unknown, sender_not_permitted, too_large, rate_limited, address_disabled, unparseable, no_sender, processing_failed
  • reason
    string | null
  • target_type
    stringrequired
    One of: rfi, submittal, ap_invoice.
  • from_address
    string
  • sender_user_id
    integer | null
  • sender_verified
    boolean
  • subject
    string | null
  • size_bytes
    integer
  • attachment_count
    integer
  • skipped_attachments
    object[]
  • skipped_attachments[].filename
    string
  • skipped_attachments[].reason
    string
  • authentication
    object | null
  • authentication.spf
    string | null
  • authentication.dkim
    string | null
  • authentication.dmarc
    string | null
  • record
    object | null
  • record.type
    string
    One of: rfi, submittal, ap_captured_document.
  • record.id
    integer | null
  • record.api_path
    string | null
  • uploaded_by_id
    integer | null
  • received_at
    string (date-time)
  • processed_at
    string (date-time) | null
  • created_at
    string (date-time)

Errors

  • 403Missing permission
  • 413Larger than the intake size limit
  • 422No file

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/email_intake/messages" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "file": "string"
}'
GET /rest/v1.0/projects/{project_id}/email_intake/messages/{id}

Show an email intake log entry

Requires the project Admin tool at admin level (token scope admin:read for reads, admin:write for writes).

v1.0Implemented

Parameters

  • OS-Company-Id
    integerheaderrequired
  • project_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • project_id
    integerrequired
  • address_id
    integer | null
  • source
    stringrequired
    One of: resend, eml_upload.
  • status
    stringrequired
    One of: received, drafted, rejected, failed.
  • reason_code
    string | null
    auto_reply, bulk_mail, mail_loop, bounce_sender, sender_unauthenticated, sender_unknown, sender_not_permitted, too_large, rate_limited, address_disabled, unparseable, no_sender, processing_failed
  • reason
    string | null
  • target_type
    stringrequired
    One of: rfi, submittal, ap_invoice.
  • from_address
    string
  • sender_user_id
    integer | null
  • sender_verified
    boolean
  • subject
    string | null
  • size_bytes
    integer
  • attachment_count
    integer
  • skipped_attachments
    object[]
  • skipped_attachments[].filename
    string
  • skipped_attachments[].reason
    string
  • authentication
    object | null
  • authentication.spf
    string | null
  • authentication.dkim
    string | null
  • authentication.dmarc
    string | null
  • record
    object | null
  • record.type
    string
    One of: rfi, submittal, ap_captured_document.
  • record.id
    integer | null
  • record.api_path
    string | null
  • uploaded_by_id
    integer | null
  • received_at
    string (date-time)
  • processed_at
    string (date-time) | null
  • created_at
    string (date-time)

Errors

  • 404Not found

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/email_intake/messages/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

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