Async jobs

Most Poptin API calls finish inline: you send a request, the server does the work, and you get the result in the response. A handful of write operations are different. They are accepted immediately, run in the background, and finish later. The API signals this with an HTTP 202 Accepted and a job you can poll until it reaches a terminal state.

Use this page to understand the mental model. For the exact poll parameters, response fields, and examples, see Async job polling in the API Reference.

Which actions queue

The operations that typically queue as async jobs are the ones that touch many rows or send email:

• Bulk import contacts - via JSON payload or a CSV upload.
• Bulk delete contacts - via JSON payload.
• Send template email - dispatched to subscribed contacts.

These calls do not complete inline because the work can be large, slow, or externally rate-limited (email delivery in particular). Accepting them as jobs keeps request latencies predictable and lets Poptin schedule the work sensibly.

The poll pattern

Every async job follows the same shape:

1. Queue the work. Call the write operation. A successful response returns 202 Accepted along with a job identifier that uniquely names this run.
2. Poll job status. Ask the bulk-jobs endpoint for the current state of that job on an interval. Do not poll in a tight loop - pick a reasonable cadence and back off if the job is long-running.
3. Wait for a terminal state. Jobs end in either done (the work finished) or failed (the work stopped and the outcome is not usable). Anything else is still in progress.
4. Read the outcome. On completion, inspect the job for counts, errors, and any per-row failure detail. On failure, use the reported error to decide whether to fix input and re-queue.

Design your client to treat the initial 202 as "the request landed," not "the work is done." Only the final job state answers that.

Concurrency

Async jobs are subject to concurrency limits. The exact limits may vary by account and can change over time, so design your client to react to the API's response rather than to a hardcoded number.

If a new job cannot start because concurrency is exhausted, the API typically returns HTTP 409 Conflict. When that happens:

• Wait for an in-progress job to reach a terminal state (or otherwise free capacity).
• Retry the queuing call once capacity is available.
• Do not tight-loop on the queuing endpoint. Aggressive retries won't create capacity and can trip rate limits unnecessarily.

Exception: poptin stats refresh

Not every asynchronous operation flows through the bulk-jobs poll pattern. Requesting a poptin stats refresh also runs in the background, but you track its progress on the poptin resource itself - its refresh status and last-updated timestamp - rather than by polling a job. Treat it as an object-level state change, not a bulk job.

Next steps