Jobs

Use jobs to deliver a notification or to require a recipient to complete an email proof flow. Create a draft job after its message group has been prepared, then activate it.

Authentication

Every route on this page requires a bearer token for a user, admin, or root principal. The API scopes every job to that principal; do not send owner.

Routes

Route	Required fields	Optional fields and behavior
`POST /v1/members/job/create`	On creation: `purpose`, `proof_policy`; on update: `id`	`message_group`, `email`, `sms`, `metadata`, and draft `status`.
`POST /v1/members/job/get`	`id`	Returns the owned job and its delivery requests.
`POST /v1/members/job/list`	None	Filters: `id`, `message_group`, `proof_policy`, `purpose`, `status`, and shared pagination.
`POST /v1/members/job/activate`	`id`	Activates a draft job after its group, templates, and contacts pass activation rules.
`POST /v1/members/job/cancel`	`id`	Cancels a draft or active job.
`POST /v1/members/job/retry`	`id`	Creates a new draft clone of a completed, failed, or cancelled job.

Create or update a draft job

/v1/members/job/create creates a job when id is omitted. With an owned draft-job id, it updates that draft. A non-draft job cannot be changed by this route.

Request fields

Field	Required	Type	Description
`id`	No	UUID	Existing owned draft job to update.
`purpose`	Yes on create	String	The purpose shown to the recipient and used in message snapshots. An update may omit it to retain the existing value.
`proof_policy`	Yes on create	String	`single`, `any`, or `none`. An update may omit it to retain the existing value. See activation.
`message_group`	No at creation; yes at activation	UUID or String	Owned message-group ID or name.
`email`	No at creation; conditional at activation	String or array of strings	Recipient email addresses. A newline-separated string is also accepted.
`sms`	No at creation	String or array of strings	SMS contact values. A newline-separated string is also accepted.
`metadata`	No	Object or `null`	Application-defined job data.
`status`	No	String	Only `draft` is accepted on this route. New jobs are `draft`.

Supplying email or sms replaces every contact method of that type on the draft job. On an update, omitted job fields retain their existing values.

curl -sS https://api.post.m7.org/v1/members/job/create \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "purpose": "Confirm an email address",
    "proof_policy": "single",
    "message_group": "email-proof",
    "email": ["recipient@example.test"],
    "metadata": { "source": "signup" }
  }'

{
  "status": 1,
  "comment": "OK",
  "data": {
    "created": true,
    "item": {
      "id": "JOB_UUID",
      "message_group": "MESSAGE_GROUP_UUID",
      "purpose": "Confirm an email address",
      "proof_policy": "single",
      "status": "draft",
      "email": ["recipient@example.test"],
      "sms": [],
      "checks": {
        "dne": null,
        "domain": null,
        "blocked": false
      }
    }
  }
}

Store data.item.id; activation and the proof flow use it.

Read and list jobs

/get requires id and returns data.item. Along with the job fields shown above, it returns email_requests for the job. /list returns the shared paged object in data; each item includes email, sms, and checks.

message_group accepts an ID or an owned message-group name when used as a list filter. status accepts draft, active, completed, failed, or cancelled; all removes the status filter. The legacy values prepare and complete normalize to draft and completed respectively.

Activate a job

/v1/members/job/activate accepts only id:

{ "id": "JOB_UUID" }

Activation is allowed only for a draft job. The job must have an owned message group, and that group must contain a template for the delivery channel. At least one contact method is required. Email values must be valid email addresses.

`proof_policy`	Activation result
`single`	Requires exactly one contact method, which must be email. The job becomes `active`; its email challenge is sent automatically.
`any`	Requires at least one contact method and an eligible email method. The job becomes `active`; the first eligible email method is armed.
`none`	Requires at least one email method. The notification is sent and the job becomes `completed`.

The response places activated: true and the updated job in data.item. For an active proof job, continue with the proof flow.

Cancel or retry

/cancel accepts an owned job id. Only draft and active jobs can be cancelled. Its response contains data.cancelled: true and the cancelled data.item.

/retry accepts an owned job id. Only completed, failed, and cancelled jobs can be retried. It returns data.retried: true and a new draft job in data.item; the new job has a new ID and carries the original contact methods.

Errors and state

A missing or unowned id returns Job not found.
Editing or activating a job outside the allowed state fails with a conflict.
Activation fails when its message group is missing, belongs to another principal, has no eligible template, or its proof-policy contact rule is not met.
A proof job remains active until proof consumption succeeds. Consumption changes it to completed.