Fieldmotion API Getting started

Email imports: configuration and diagnostics

Send a real message to a job import address

POST /a/ImportJobsEmail_sendSampleEmail

Send a body and subject to an owned email-import address through the outbound mail service.

When to use this endpoint

Exercise the email delivery and background import path after configuring extraction rules. Use only an import address and message content for which creating real records is intended; this is not a server-side preview parser.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. The handler requires login but performs no separate page, administrator, or role-permission check.

Requires Import By Email feature bit 32768. The global lookup checks the authenticated tenant owner but does not require job type 0, so an owned customer/task routing configuration can also receive this message.

Parameters

ParameterTypeRequiredDescription
idIntegerYesPositive global import-filter ID after intval().
bodyStringYesTruthy body text. Empty text and "0" are rejected; whitespace-only text is not trimmed away.
subjectStringNoDefaults to [FM] sample email followed by the current Unix timestamp. A supplied empty subject is retained. The body/subject are not read from the stored sample fields.

Example request

$result = FM_api('ImportJobsEmail_sendSampleEmail', [
	'id' => '1042',
	'body' => 'Name: Example Services; Email: office@example.com',
	'subject' => 'Website enquiry test',
]);

Example response

{
  "id": "1042",
  "owner_id": "12345",
  "recipient": "0123456789abcdef0123456789abcdef",
  "regexps": "[]",
  "form_id": "27",
  "sample_email": "",
  "sample_email_import": null,
  "form_by_regexp": "",
  "spreadsheets": "[]",
  "regexps_table": "[]",
  "regexps_table_delimiters": "{\"start\":\"\",\"end\":\"\",\"item_start\":\"\",\"item_end\":\"\"}",
  "type": "0",
  "name": null,
  "last_edited": "0",
  "sample_email_subject": "",
  "notes": null,
  "meta": null
}

Returns the complete raw filter snapshot read before sending, not a mail queue ID, an ok object, or a parsed import result. Database scalars and stored JSON strings retain their raw-row types; nullable defaults can vary.

The handler requires an affirmative ok acknowledgement from the mail service before returning the raw filter. An absent, malformed, or negative acknowledgement returns an explicit error; it does not prove non-delivery, so inspect mail history before retrying.

Errors and unusual responses

ResponseCondition
{"error":"not logged in"}No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
{"error":"missing or invalid parameter: id"}Nonpositive integer-converted ID, before login.
{"error":"missing or invalid parameter: body"}Missing or false-like body, before login.
{"error":"Import By Email feature not enabled"}Account feature disabled.
{"error":"this import does not exist"}No filter owned by this tenant was found.
{"error":"Sample email was not acknowledged. Check mail history before retrying."}The mail handoff did not return an affirmative ok response. No automatic retry occurs.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • The recipient is the stored token plus @import.fieldmotion.com; a caller cannot supply an arbitrary destination through this parameter set.
  • Neither sample_email nor sample_email_subject is saved from this request. There is no synchronous parser result or status polling token.
  • The background worker’s exact subject test email takes a special early log-only branch. The normal default sample subject does not use that branch. Capture flags also do not make an ordinary message a dry run.

Side effects

  • Calls Core_mail with the authenticated company/user, type 2, the routing address as its recipient list, and template ID -1. Mail metadata includes body, subject, and creation trigger ImportJobsEmail_sendSampleEmail with object type import and object ID 0.
  • Does not directly update configuration timestamps or write a configuration history entry. Mail-service delivery and later worker/import effects occur outside this request’s persistence guarantees.

See it in Fieldmotion

CRM1

In Imports → Jobs by Email, open the editor’s Sample tab, enter body/subject, then use Send and confirm the “I am sure” prompt. Filter for ImportJobsEmail_sendSampleEmail; the confirmation is UI-only.

CRM2

In Jobs by Email, open the edit widget’s Sample tab and use Send. The widget also prompts before calling ImportJobsEmail_sendSampleEmail. Inspect the outgoing body/subject in developer tools.

Related endpoints