Hello world
| | cc | string | no | CC recipients (optional) | | | bcc | string | no | BCC recipients (optional) | | | lead_id | string | no | Associate email with a contact ID (optional) | | | opportunity_id | string | no | Associate email with an opportunity ID (optional) | | | signature_id | string | no | Append this signature to the email (optional, get from signatures/get) | | | tracking | string | no | Enable open tracking, set to "y" (optional) | | Example: ```bash curl -X POST 'https://api.datalyse.io/api/1.0/emails/send.json' \ -H 'Content-Type: application/json' \ -d '{"token":"YOUR_APIKEY","to":"","subject":"Hello","html":"Hello world
"}' ``` ### email_get_inbox `POST https://api.datalyse.io/api/1.0/emails/get.json` Get emails from inbox or sent folder | Parameter | Type | Required | Description | Example | |---|---|---|---|---| | token | string | yes | API access token | YOUR_APIKEY | | type | string | yes | Folder: "inbox" (default) or "sent" | inbox | | var_resultspage | string | yes | Maximum number of results | 20 | | var_page | string | yes | Page number | 1 | | search_value | string | no | Search in subject (optional) | | | unread_only | string | no | Show only unread, set to "y" (optional) | | Example: ```bash curl -X POST 'https://api.datalyse.io/api/1.0/emails/get.json' \ -H 'Content-Type: application/json' \ -d '{"token":"YOUR_APIKEY","type":"inbox","var_resultspage":"20","var_page":"1"}' ``` ### email_get_one `POST https://api.datalyse.io/api/1.0/emails/getone.json` Get a single email with full body | Parameter | Type | Required | Description | Example | |---|---|---|---|---| | token | string | yes | API access token | YOUR_APIKEY | | email_id | string | yes | ID of the email | | Example: ```bash curl -X POST 'https://api.datalyse.io/api/1.0/emails/getone.json' \ -H 'Content-Type: application/json' \ -d '{"token":"YOUR_APIKEY","email_id":""}' ``` ### email_get_signatures `POST https://api.datalyse.io/api/1.0/emails/signatures/get.json` Get all email signatures | Parameter | Type | Required | Description | Example | |---|---|---|---|---| | token | string | yes | API access token | YOUR_APIKEY | Example: ```bash curl -X POST 'https://api.datalyse.io/api/1.0/emails/signatures/get.json' \ -H 'Content-Type: application/json' \ -d '{"token":"YOUR_APIKEY"}' ``` ### email_save_signature `POST https://api.datalyse.io/api/1.0/emails/signatures/save.json` Create or update an email signature | Parameter | Type | Required | Description | Example | |---|---|---|---|---| | token | string | yes | API access token | YOUR_APIKEY | | signature_id | string | yes | ID of signature to update (omit to create new) | | | name | string | yes | Signature name | My Signature | | html | string | yes | Signature HTML content |Best regards
| | is_default | string | yes | Set as default signature, "true" or "false" | false | Example: ```bash curl -X POST 'https://api.datalyse.io/api/1.0/emails/signatures/save.json' \ -H 'Content-Type: application/json' \ -d '{"token":"YOUR_APIKEY","signature_id":"","name":"My Signature","html":"Best regards
","is_default":"false"}' ``` ### email_delete_signature `POST https://api.datalyse.io/api/1.0/emails/signatures/delete.json` Delete an email signature | Parameter | Type | Required | Description | Example | |---|---|---|---|---| | token | string | yes | API access token | YOUR_APIKEY | | signature_id | string | yes | ID of the signature to delete | | Example: ```bash curl -X POST 'https://api.datalyse.io/api/1.0/emails/signatures/delete.json' \ -H 'Content-Type: application/json' \ -d '{"token":"YOUR_APIKEY","signature_id":""}' ``` ### email_get_templates `POST https://api.datalyse.io/api/1.0/emails/templates/get.json` Get all email templates | Parameter | Type | Required | Description | Example | |---|---|---|---|---| | token | string | yes | API access token | YOUR_APIKEY | Example: ```bash curl -X POST 'https://api.datalyse.io/api/1.0/emails/templates/get.json' \ -H 'Content-Type: application/json' \ -d '{"token":"YOUR_APIKEY"}' ``` ### email_create_template `POST https://api.datalyse.io/api/1.0/emails/templates/create.json` Create a new email template | Parameter | Type | Required | Description | Example | |---|---|---|---|---| | token | string | yes | API access token | YOUR_APIKEY | | name | string | yes | Template name | My Template | | subject | string | no | Default email subject (optional) | | | html | string | yes | Template HTML content |Hello {{name}}
| Example: ```bash curl -X POST 'https://api.datalyse.io/api/1.0/emails/templates/create.json' \ -H 'Content-Type: application/json' \ -d '{"token":"YOUR_APIKEY","name":"My Template","html":"Hello {{name}}
"}' ``` ### email_edit_template `POST https://api.datalyse.io/api/1.0/emails/templates/edit.json` Edit an email template | Parameter | Type | Required | Description | Example | |---|---|---|---|---| | token | string | yes | API access token | YOUR_APIKEY | | template_id | string | yes | ID of the template to edit | | | name | string | no | Template name (optional) | | | subject | string | no | Default email subject (optional) | | | html | string | no | Template HTML content (optional) | | Example: ```bash curl -X POST 'https://api.datalyse.io/api/1.0/emails/templates/edit.json' \ -H 'Content-Type: application/json' \ -d '{"token":"YOUR_APIKEY","template_id":""}' ``` ### email_delete_template `POST https://api.datalyse.io/api/1.0/emails/templates/delete.json` Delete an email template | Parameter | Type | Required | Description | Example | |---|---|---|---|---| | token | string | yes | API access token | YOUR_APIKEY | | template_id | string | yes | ID of the template to delete | | Example: ```bash curl -X POST 'https://api.datalyse.io/api/1.0/emails/templates/delete.json' \ -H 'Content-Type: application/json' \ -d '{"token":"YOUR_APIKEY","template_id":""}' ``` ## Emailservices ### email_list_domains `GET https://api.datalyse.io/api/1.0/emailservices/domains.json` List the domains available to create a new email account / mailbox for the authenticated agent (use this before email_create_account to know which domains the user can create an email on). The result is the intersection of emelyse.com plus active mail_domains owned by the token company with domains reported active by the mail provider. SMTP/IMAP settings are server-authoritative. | Parameter | Type | Required | Description | Example | |---|---|---|---|---| | token | string | yes | API access token for the agent whose mailbox will be configured. Scoped app tokens require the emailservices scope. The company and agent are derived only from this token. | YOUR_APIKEY | Example: ```bash curl 'https://api.datalyse.io/api/1.0/emailservices/domains.json?token=YOUR_APIKEY' ``` Errors: - HTTP 401 — `EMPTY_TOKEN \| error_apitokennotfound \| token_type_not_allowed \| token_company_mismatch`: The token is missing, invalid, disabled or not bound to the authenticated agent company. - HTTP 403 — `scope_denied \| permission_denied`: The app token lacks the emailservices scope or the authenticated account is not allowed. - HTTP 502 — `mail_provider_unavailable \| mail_provider_rejected \| mail_provider_invalid_response`: The bounded provider request failed or returned an unexpected status/JSON shape. - HTTP 503 — `mail_provider_not_configured`: MAIL_API_URL, MAIL_ADMIN_EMAIL and MAIL_ADMIN_PASSWORD are not all configured in the server environment. - HTTP 504 — `mail_provider_timeout`: The mail provider did not answer before the configured timeout. - HTTP 500 — `internal_error`: An unexpected tenant-domain or configuration mapping read failed. Notes: - The endpoint never accepts company_id or agent_id. Tenant and agent identity come exclusively from apibridge_authorize and the token. - A Mongo mail_domains row is not sufficient: every returned domain is rechecked as active against the mail provider. - Responses use Cache-Control: no-store and expose no provider credentials or mailbox passwords. ### email_create_account `POST https://api.datalyse.io/api/1.0/emailservices/create.json` Create a new email account / mailbox on a managed domain and configure it for the agent authenticated by token (this is the tool to use when the user asks to create an email, create a mailbox, or set up a new email address like name@yourdomain.com). The shared socket/HTTP core validates tenant domain ownership and live provider state, creates and verifies the new mailbox before an atomic local switch, then disconnects the old poller and removes only a strictly owned previous managed mailbox. HTTP calls require an idempotency key. | Parameter | Type | Required | Description | Example | |---|---|---|---|---| | token | string | yes | API access token for the agent being configured. Scoped app tokens require the emailservices scope. company_id and agent_id are always derived from this token. | YOUR_APIKEY | | email | string | yes | Full ASCII mailbox address. The local part is 1-64 characters, starts with an alphanumeric character and permits alphanumerics, dot, underscore, plus and hyphen; consecutive/trailing dots are rejected. Domain must be emelyse.com or an active mail_domains row owned exactly by the token company. | support@emelyse.com | | password | string | no | Optional mailbox password. If omitted or empty, the server generates one with crypto.randomBytes. Supplied values must be 12-128 visible ASCII characters and contain lowercase, uppercase, digit and symbol. | | | idempotency_key | string | yes | Required HTTP idempotency key, 8-128 characters from A-Z, a-z, 0-9, dot, underscore, colon or hyphen. The same key and payload replays without creating another mailbox; the same key with a different email/password returns idempotency_conflict. | mail-create-20260726-001 | Example: ```bash curl -X POST 'https://api.datalyse.io/api/1.0/emailservices/create.json' \ -H 'Content-Type: application/json' \ -d '{"token":"YOUR_APIKEY","email":"support@emelyse.com","idempotency_key":"mail-create-20260726-001"}' ``` Generate a strong password server-side: ```json { "token": "YOUR_APIKEY", "email": "support@emelyse.com", "idempotency_key": "mail-create-20260726-001" } ``` Use a caller-supplied strong password: ```json { "token": "YOUR_APIKEY", "email": "sales@owned.example", "password": "ExampleStrongPass123!", "idempotency_key": "mail-create-20260726-002" } ``` Errors: - HTTP 400 — `invalid_request \| email_required \| invalid_email \| invalid_local_part \| invalid_password \| idempotency_key_required \| invalid_idempotency_key \| conflicting_idempotency_key \| agent_id_not_allowed \| company_id_not_allowed`: The request shape, address, password or HTTP idempotency key is invalid. Raw agent_id and company_id overrides are rejected before authentication normalization. - HTTP 401 — `EMPTY_TOKEN \| error_apitokennotfound \| token_type_not_allowed \| token_company_mismatch`: The API token is missing, invalid, disabled or bound to a different tenant. - HTTP 403 — `scope_denied \| permission_denied \| domain_not_allowed`: The token lacks emailservices scope/permission or the requested domain is not active and owned exactly by the token company. - HTTP 404 — `agent_not_found`: The authenticated agent no longer exists in the token company. - HTTP 409 — `idempotency_conflict \| operation_in_progress \| recovery_manual_required \| domain_not_active \| email_in_use \| configuration_changed`: The idempotency key has a different payload, another live lease holds the company+agent lock, uncertain stale provider state requires manual reconciliation, the provider domain is inactive, the mailbox already exists, or local mail state changed concurrently. - HTTP 500 — `persistence_failed \| internal_error`: The local atomic switch failed. A mailbox created by this operation is compensated only after strict provider id/email/company/agent verification. - HTTP 502 — `mail_provider_unavailable \| mail_provider_rejected \| mail_provider_invalid_response \| mail_provider_verification_failed`: The provider request failed, returned an unexpected bounded JSON/status, or the newly created mailbox could not be verified. - HTTP 503 — `mail_provider_not_configured \| safety_unavailable`: Required provider environment credentials are absent or the unique lock/idempotency indexes are unavailable. - HTTP 504 — `mail_provider_timeout`: A mail provider operation exceeded its configured timeout. Notes: - HTTP 201 means the mailbox was created and committed. HTTP 200 means an idempotent replay of the same completed job. A concurrent in-progress job returns HTTP 409 plus Retry-After. - SENSITIVE RESPONSE: password is the only returned secret. Store it securely and never cache or log the response. The API sends Cache-Control: no-store, private and Pragma: no-cache. - On replay, password is read only from the same authenticated agent when emailservices_job_id and request hash still match this exact job. If the agent later changes configuration, password is null and password_available is false. - The new provider mailbox is created and re-read with exact company_id and agent_id before any local/OAuth/poller/old-mailbox change. Mongo transaction failure leaves old local/OAuth state intact and triggers deletion only of the verified mailbox created by this job. - OAuth connections and clients_azure are removed inside the local transaction. Poller disconnection and strictly-owned previous managed-mailbox deletion happen only after commit; pending cleanup is retried by an exact idempotent replay. - The operation is serialized by a unique active company_id+agent_id lock plus a 60-300 second fenced lease (180 seconds by default). A stale claimed job can be taken over by the same idempotency key. - A stale job with an exact provider marker is resumed only after matching provider user id, domain id, email, company_id and agent_id. If a generated password was lost in a crash, that exact marked mailbox is compensated and recreated; ambiguous pre-marker state returns recovery_manual_required and releases the active lock. - Terminal idempotency jobs expire through a TTL index after 24 hours. Passwords are never stored in job documents or logs. - MAIL_API_URL, MAIL_ADMIN_EMAIL and MAIL_ADMIN_PASSWORD must be supplied by the server environment; the shared core has no credential fallback. ## Entities ### entities_get_schemas `POST https://api.datalyse.io/api/1.0/entities/schemas.json` Discover ALL CRM entities and their complete schemas in one call. This is the mandatory entry point for AI assistants and MCP integrations before reading or writing records. The built-in record entities (leads/contacts, companies, opportunities, tasks, tickets, and — when the deployment enables finance entities — budgets and payments) and every custom entity (cust_...) expose the SAME record contract: properties contains the exact identifiers accepted inside values; direct associations are writable properties of type 'association'; statusgroups tells which value to send for each status field; and record_api contains the same generic endpoints to list, get, create, edit, delete, read activity and add notes. Status value rule: mode='index' -> send legacyIndex, mode='id' -> send id, mode='value' -> send id/value, always under values[statusgroups[].docField]. Properties with read_only=true must not be written. Budgets and payments: check record_api.supported per entity — when true they use the same generic record endpoints (budgets add a 'lineitems' property 'concepts' whose value is an array of row objects following properties.concepts.lineitems.columns, and payments amounts are declared stored_as='string' but always read and written as numbers here); when false they keep their document-specific endpoints listed in record_api. Budgets id_lead/idsale are set at creation and immutable afterwards; payments create is also available via the specific endpoint /api/1.0/payments/create.json (contract unchanged). GET is also supported with token in the query string. EVERY property always includes required:'y'\|'n' and unique:'y'\|'n' for both system and custom entities; omitted internal flags are normalized to 'n'. | Parameter | Type | Required | Description | Example | |---|---|---|---|---| | token | string | yes | API access token of the company. Required. | YOUR_APIKEY | Example: ```bash curl -X POST 'https://api.datalyse.io/api/1.0/entities/schemas.json' \ -H 'Content-Type: application/json' \ -d '{"token":"YOUR_APIKEY"}' ``` Get all entities and schemas: ```json { "token": "YOUR_APIKEY" } ``` Errors: - `EMPTY_TOKEN`: Missing token parameter - `error_apitokennotfound`: Token not found or not authorized - `company_not_found`: The company linked to the token no longer exists - `server_error`: Unexpected server error Notes: - Call this endpoint first and cache its result only for the current company/token. Never guess entity keys, property identifiers, status values or association fields. - UNIFORM RECORD API: leads, companies, opportunities, tasks, tickets and cust_* all use record_api.list/get/create/edit/delete/activity/add_note. The old module-specific endpoints remain compatible, but MCP/AI should prefer record_api. - STATUS VALUES: use the group's docField as the field name inside values. mode='index' uses legacyIndex; mode='id' uses id; mode='value' uses the status id/value. The first status flagged isdefault='y' is used when creation omits it. - ASSOCIATIONS: direct links are also exposed as properties with type='association'. Send the target record's 24-character id as values[association.identifier]. Associations with inverse='y' are calculated collections and cannot be written. - read_only=true means the property can be returned and filtered but must not be sent to create/edit. Dates use unix UTC epoch seconds; accepted date strings are normalized server-side where documented. - Budgets are intentionally outside the uniform record contract; follow their specific hints instead of calling /entities record operations. - PROPERTY CONSTRAINT FLAGS: every properties entry always returns required ('y' or 'n') and unique ('y' or 'n'), including system, status, assignment and association properties. required='y' means a value is mandatory on creation; unique='y' means no other record of that entity may use the same non-empty value. ### entities_get_records `POST https://api.datalyse.io/api/1.0/entities/getrecords.json` Search and list records through one POST endpoint for contacts (entitykey 'leads'), companies, opportunities, tasks, tickets and every custom entity (cust_...). Call schemas.json first, then use its property identifiers in filters/orderby. Filters support eq, ne, in, nin, gt, gte, lt, lte and re, including several operators on one field for ranges. The response has one stable shape for system and custom entities: clean records with id, schema properties, assignment fields, epoch-second dates, resolvedWe will contact you shortly.
","assignment":"current","tracking":true}},{"key":"b:notify-owner","block_type":"sendnoti","payload":{"assignment":"current","title":"Qualified lead","text":"A qualified lead requires follow-up.","send_notification":true}}]}}' ``` Complete v1 contact workflow with a branch: ```json { "token": "YOUR_APIKEY", "fortype": "leads", "name": "Qualified lead follow-up", "idempotency_key": "workflow:create:qualified-followup:v1", "definition": { "version": 1, "activator": { "conditions": [ [ { "fortype": "leads", "identifier": "status", "op": "eq", "text": "qualified" } ] ] }, "entry": "b:wait", "blocks": [ { "key": "b:wait", "block_type": "delay", "next": "b:segment", "payload": { "minutes": 5 } }, { "key": "b:segment", "block_type": "bifurcation", "payload": { "conditions": [ [ { "fortype": "leads", "identifier": "leadtypedatal", "op": "eq", "text": "vip" } ], [ { "fortype": "leads", "identifier": "leadtypedatal", "op": "ne", "text": "vip" } ] ], "conditions_next": [ "b:email-vip", "b:notify-owner" ] } }, { "key": "b:email-vip", "block_type": "sendemail", "payload": { "to": "client", "subject": "Your account is ready", "text": "We will contact you shortly.
", "assignment": "current", "tracking": true } }, { "key": "b:notify-owner", "block_type": "sendnoti", "payload": { "assignment": "current", "title": "Qualified lead", "text": "A qualified lead requires follow-up.", "send_notification": true } } ] } } ``` Legacy header-only workflow: ```json { "token": "YOUR_APIKEY", "fortype": "opportunities", "name": "Opportunity won follow-up" } ``` Errors: - HTTP 400 — `invalid_fortype \| invalid_name \| idempotency_key_required \| invalid_idempotency_key \| unexpected_field \| client_supplied_id`: Invalid common fields, unsupported fortype, missing complete-mode retry key, unknown input, or an attempt to supply server-owned IDs. - HTTP 400 — `invalid_definition \| unsupported_definition_version \| invalid_activator \| activator_requires_conditions_or_event \| workflow_event_requires_events_fortype \| events_fortype_requires_workflow_event \| invalid_workflow_event \| invalid_conditions \| invalid_condition_group \| invalid_condition \| invalid_condition_fortype \| invalid_condition_field \| invalid_condition_operator \| invalid_condition_value`: definition.version/activator/condition structure or values are invalid. - HTTP 400 — `invalid_block \| invalid_block_type \| invalid_block_payload \| invalid_json_value \| invalid_object_key \| payload_field_required \| invalid_payload_field \| payload_field_too_large \| conflicting_payload_fields \| invalid_reference_id \| duplicate_reference_id \| assignment_targets_required \| invalid_whatsapp_template_json \| webhook_https_required \| invalid_webhook_url \| webhook_private_destination \| webhook_host_not_resolvable`: A block payload failed its type-specific allowlist, tenant-reference format, size, assignment, JSON, or public HTTPS webhook validation. - HTTP 400 — `invalid_block_reference \| duplicate_block_key \| workflow_graph_missing_entry \| workflow_graph_missing_reference \| workflow_graph_cycle \| workflow_graph_orphan_blocks \| workflow_graph_multiple_parents \| workflow_graph_entry_has_parent \| invalid_branch_references \| branch_reference_count_mismatch`: Temporary b:* references do not form one complete rooted acyclic graph. - HTTP 400 — `reference_not_found_or_cross_tenant`: An agent, department or queue reference is absent from the token company; cross-company existence is not disclosed. - HTTP 401 — `EMPTY_TOKEN \| error_apitokennotfound \| client_id_not_found \| conflicting_token \| token_type_not_allowed \| client_disabled \| company_not_found \| token_company_mismatch`: Missing or invalid API token - HTTP 403 — `permission_denied \| scope_denied \| plan_restricted`: Token user lacks manageworkflows/workflows scope, workflows are disabled by plan, or a multi-object graph is not allowed. Plan lookup fails closed for multi-object workflows. - HTTP 409 — `workflow_limit_reached \| idempotency_conflict`: Company reached 500 workflows, or the same idempotency_key was reused with a different normalized payload. - HTTP 413 — `workflow_definition_too_large \| workflow_block_too_large \| workflow_graph_too_large`: Definition exceeds 512 KiB, one payload exceeds 32 KiB, or the graph exceeds 200 blocks. - HTTP 500 — `internal_error \| insert_failed \| transaction_not_committed \| idempotency_replay_corrupt`: Unexpected persistence failure or an incomplete historical idempotency record. Notes: - AI SAFETY: creation never activates or executes a workflow. The persisted workflow status and response workflow_status are always 0. - Legacy compatibility: omit definition to retain header-only creation; legacy idempotency_key remains optional. - Complete mode: definition.version=1 and idempotency_key are mandatory. Header and every block are inserted in one majority MongoDB transaction. - Idempotency compares a SHA-256 hash of the normalized fortype, requested name and complete definition. Identical replay is HTTP 200; changed payload is HTTP 409. - All graph IDs are generated server-side. Clients only use temporary keys matching b: