Email Intake
- GET
/rest/v1.0/projects/{project_id}/email_intake/addressesList inbound email addresses - POST
/rest/v1.0/projects/{project_id}/email_intake/addressesCreate an inbound email address - GET
/rest/v1.0/projects/{project_id}/email_intake/addresses/{id}Show an inbound email address - PATCH
/rest/v1.0/projects/{project_id}/email_intake/addresses/{id}Update an inbound email address - POST
/rest/v1.0/projects/{project_id}/email_intake/addresses/{id}/rotateRotate an inbound email address - GET
/rest/v1.0/projects/{project_id}/email_intake/messagesList the email intake log - POST
/rest/v1.0/projects/{project_id}/email_intake/messagesUpload an .eml as a draft - GET
/rest/v1.0/projects/{project_id}/email_intake/messages/{id}Show an email intake log entry
/rest/v1.0/projects/{project_id}/email_intake/addressesList inbound email addresses
Requires the project Admin tool at admin level (token scope admin:read for reads, admin:write for writes).
Parameters
- OS-Company-Idintegerheaderrequired
- project_idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- project_idintegerrequired
- addressstringrequiredThe full inbound address, <slug>-<token>@<inbound domain>.
- labelstring | null
- target_typestringrequiredOne of: rfi, submittal, ap_invoice.
- enabledbooleanrequired
- receiving_enabledbooleanrequiredWhether the platform currently receives mail (INBOUND_EMAIL_ENABLED). Uploading .eml works either way.
- created_by_idinteger
- rotated_atstring (date-time) | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
403Not a project admin
Example request
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/email_intake/addresses" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/projects/{project_id}/email_intake/addressesCreate an inbound email address
Requires the project Admin tool at admin level (token scope admin:read for reads, admin:write for writes).
Parameters
- OS-Company-Idintegerheaderrequired
- project_idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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_addressobjectrequired
- inbound_address.labelstring | null
- inbound_address.target_typestringOne of: rfi, submittal, ap_invoice.
Response · 201 · object
- idintegerrequired
- project_idintegerrequired
- addressstringrequiredThe full inbound address, <slug>-<token>@<inbound domain>.
- labelstring | null
- target_typestringrequiredOne of: rfi, submittal, ap_invoice.
- enabledbooleanrequired
- receiving_enabledbooleanrequiredWhether the platform currently receives mail (INBOUND_EMAIL_ENABLED). Uploading .eml works either way.
- created_by_idinteger
- rotated_atstring (date-time) | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
403Not a project admin422Invalid body
Example request
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": {}
}'/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).
Parameters
- OS-Company-Idintegerheaderrequired
- project_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- project_idintegerrequired
- addressstringrequiredThe full inbound address, <slug>-<token>@<inbound domain>.
- labelstring | null
- target_typestringrequiredOne of: rfi, submittal, ap_invoice.
- enabledbooleanrequired
- receiving_enabledbooleanrequiredWhether the platform currently receives mail (INBOUND_EMAIL_ENABLED). Uploading .eml works either way.
- created_by_idinteger
- rotated_atstring (date-time) | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
404Not found
Example request
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/email_intake/addresses/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/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.
Parameters
- OS-Company-Idintegerheaderrequired
- project_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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_addressobjectrequired
- inbound_address.labelstring | null
- inbound_address.target_typestringOne of: rfi, submittal, ap_invoice.
- inbound_address.enabledboolean
Response · 200 · object
- idintegerrequired
- project_idintegerrequired
- addressstringrequiredThe full inbound address, <slug>-<token>@<inbound domain>.
- labelstring | null
- target_typestringrequiredOne of: rfi, submittal, ap_invoice.
- enabledbooleanrequired
- receiving_enabledbooleanrequiredWhether the platform currently receives mail (INBOUND_EMAIL_ENABLED). Uploading .eml works either way.
- created_by_idinteger
- rotated_atstring (date-time) | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
404Not found422Invalid body
Example request
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": {}
}'/rest/v1.0/projects/{project_id}/email_intake/addresses/{id}/rotateRotate 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.
Parameters
- OS-Company-Idintegerheaderrequired
- project_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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
- idintegerrequired
- project_idintegerrequired
- addressstringrequiredThe full inbound address, <slug>-<token>@<inbound domain>.
- labelstring | null
- target_typestringrequiredOne of: rfi, submittal, ap_invoice.
- enabledbooleanrequired
- receiving_enabledbooleanrequiredWhether the platform currently receives mail (INBOUND_EMAIL_ENABLED). Uploading .eml works either way.
- created_by_idinteger
- rotated_atstring (date-time) | null
- created_atstring (date-time)
- updated_atstring (date-time)
Errors
404Not found
Example request
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)"/rest/v1.0/projects/{project_id}/email_intake/messagesList 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.
Parameters
- OS-Company-Idintegerheaderrequired
- project_idintegerpathrequired
- statusstringqueryOne of: received, drafted, rejected, failed.
- address_idintegerquery
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- project_idintegerrequired
- address_idinteger | null
- sourcestringrequiredOne of: resend, eml_upload.
- statusstringrequiredOne of: received, drafted, rejected, failed.
- reason_codestring | nullauto_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
- reasonstring | null
- target_typestringrequiredOne of: rfi, submittal, ap_invoice.
- from_addressstring
- sender_user_idinteger | null
- sender_verifiedboolean
- subjectstring | null
- size_bytesinteger
- attachment_countinteger
- skipped_attachmentsobject[]
- skipped_attachments[].filenamestring
- skipped_attachments[].reasonstring
- authenticationobject | null
- authentication.spfstring | null
- authentication.dkimstring | null
- authentication.dmarcstring | null
- recordobject | null
- record.typestringOne of: rfi, submittal, ap_captured_document.
- record.idinteger | null
- record.api_pathstring | null
- uploaded_by_idinteger | null
- received_atstring (date-time)
- processed_atstring (date-time) | null
- created_atstring (date-time)
Errors
403Not a project admin
Example request
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/email_intake/messages" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/projects/{project_id}/email_intake/messagesUpload 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.
Parameters
- OS-Company-Idintegerheaderrequired
- project_idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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_typestringqueryOne of: rfi, submittal, ap_invoice.
Request body
- filestring (binary)requiredThe .eml file (message/rfc822).
Response · 200 · object
- idintegerrequired
- project_idintegerrequired
- address_idinteger | null
- sourcestringrequiredOne of: resend, eml_upload.
- statusstringrequiredOne of: received, drafted, rejected, failed.
- reason_codestring | nullauto_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
- reasonstring | null
- target_typestringrequiredOne of: rfi, submittal, ap_invoice.
- from_addressstring
- sender_user_idinteger | null
- sender_verifiedboolean
- subjectstring | null
- size_bytesinteger
- attachment_countinteger
- skipped_attachmentsobject[]
- skipped_attachments[].filenamestring
- skipped_attachments[].reasonstring
- authenticationobject | null
- authentication.spfstring | null
- authentication.dkimstring | null
- authentication.dmarcstring | null
- recordobject | null
- record.typestringOne of: rfi, submittal, ap_captured_document.
- record.idinteger | null
- record.api_pathstring | null
- uploaded_by_idinteger | null
- received_atstring (date-time)
- processed_atstring (date-time) | null
- created_atstring (date-time)
Errors
403Missing permission413Larger than the intake size limit422No file
Example request
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"
}'/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).
Parameters
- OS-Company-Idintegerheaderrequired
- project_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- project_idintegerrequired
- address_idinteger | null
- sourcestringrequiredOne of: resend, eml_upload.
- statusstringrequiredOne of: received, drafted, rejected, failed.
- reason_codestring | nullauto_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
- reasonstring | null
- target_typestringrequiredOne of: rfi, submittal, ap_invoice.
- from_addressstring
- sender_user_idinteger | null
- sender_verifiedboolean
- subjectstring | null
- size_bytesinteger
- attachment_countinteger
- skipped_attachmentsobject[]
- skipped_attachments[].filenamestring
- skipped_attachments[].reasonstring
- authenticationobject | null
- authentication.spfstring | null
- authentication.dkimstring | null
- authentication.dmarcstring | null
- recordobject | null
- record.typestringOne of: rfi, submittal, ap_captured_document.
- record.idinteger | null
- record.api_pathstring | null
- uploaded_by_idinteger | null
- received_atstring (date-time)
- processed_atstring (date-time) | null
- created_atstring (date-time)
Errors
404Not found
Example request
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/email_intake/messages/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"