Import past jobs

POST /api/v1/import/jobs stages a batch of past jobs (or customers) for a reactivation campaign. Mailr geocodes every address and stages the batch — nothing is mailed and no campaign is created. The campaign wizard reads the staged batch later, in the exact shape a CSV upload produces. Required scope: import:write · Limits: 500 rows / request, 1 MB body, 10 batches / org / UTC day

Geocoding runs before any write, so a geocoder outage never leaves a half-written batch and never burns one of your 10 daily slots. One request is one batch; there is no cross-batch dedup, and duplicate addresses within a batch are geocoded independently (the wizard’s selection step is where an operator prunes).

Retry-safe imports. Pass an optional Idempotency-Key request header (any string ≤255 chars — a UUID or hash) to make retries safe. A retry carrying a key Mailr has already seen returns the existing batch and its stored counts with 200 (not 201) — nothing is re-geocoded and no extra daily slot is spent. A retry that lands while the original request is still processing (geocoding can run for minutes) gets a 409 import_in_progress with a Retry-After header — keep retrying with the same key until you get the finished batch. A key longer than 255 chars is a 422. Keyless imports never dedup: each request stages a fresh batch. (This is replay-safety only — addresses are still never deduplicated, within a batch or across batches.)

Request

string

Optional replay key (≤255 chars). A repeat with the same key returns the existing batch (200) instead of staging a new one, or 409 while the original request is still processing; keyless requests never dedup.

string

required

jobs or customers.

array

required

1–500 rows.

string

Full mailing address (≤500 chars). A row with no address is skipped (not an error). A non-string address is an error.

string

Your id for this job/customer (≤128 chars). Optional.

string

Optional (≤200 chars).

string (ISO-8601 date)

YYYY-MM-DD (a datetime’s time part is dropped). Garbage is rejected with the offending row named. Optional.

curl -X POST https://app.getmailr.com/api/v1/import/jobs \
  -H "Authorization: Bearer $MAILR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "jobs",
    "rows": [
      {
        "external_id": "job-8842",
        "address": "3134 River Valley Dr, Austin, TX 78701",
        "customer_name": "Dana Reyes",
        "completed_at": "2026-05-02"
      },
      {
        "external_id": "job-8843",
        "address": "500 Congress Ave, Austin, TX 78701",
        "customer_name": "Sam Okafor"
      }
    ]
  }'

const res = await fetch("https://app.getmailr.com/api/v1/import/jobs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAILR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    source: "jobs",
    rows: [
      {
        external_id: "job-8842",
        address: "3134 River Valley Dr, Austin, TX 78701",
        customer_name: "Dana Reyes",
        completed_at: "2026-05-02",
      },
      {
        external_id: "job-8843",
        address: "500 Congress Ave, Austin, TX 78701",
        customer_name: "Sam Okafor",
      },
    ],
  }),
});

if (!res.ok) throw new Error(`Mailr API returned ${res.status}`);
console.log(await res.json()); // { import_id, staged, ... }

import os
import requests

payload = {
    "source": "jobs",
    "rows": [
        {
            "external_id": "job-8842",
            "address": "3134 River Valley Dr, Austin, TX 78701",
            "customer_name": "Dana Reyes",
            "completed_at": "2026-05-02",
        },
        {
            "external_id": "job-8843",
            "address": "500 Congress Ave, Austin, TX 78701",
            "customer_name": "Sam Okafor",
        },
    ],
}

res = requests.post(
    "https://app.getmailr.com/api/v1/import/jobs",
    headers={"Authorization": "Bearer " + os.environ["MAILR_API_KEY"]},
    json=payload,
)

res.raise_for_status()
print(res.json())  # {'import_id': ..., 'staged': 2, ...}

<?php
$payload = [
    "source" => "jobs",
    "rows" => [
        [
            "external_id" => "job-8842",
            "address" => "3134 River Valley Dr, Austin, TX 78701",
            "customer_name" => "Dana Reyes",
            "completed_at" => "2026-05-02",
        ],
        [
            "external_id" => "job-8843",
            "address" => "500 Congress Ave, Austin, TX 78701",
            "customer_name" => "Sam Okafor",
        ],
    ],
];

$ch = curl_init("https://app.getmailr.com/api/v1/import/jobs");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("MAILR_API_KEY"),
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status !== 201) {
    throw new RuntimeException("Mailr API returned $status: $body");
}
print_r(json_decode($body, true)); // ['import_id' => ..., 'staged' => 2, ...]

Response

201 Created

{
  "import_id": "f0e1d2c3-0000-0000-0000-000000000abc",
  "staged": 2,
  "skipped_no_address": 0,
  "skipped_geocode_failed": 0
}

The three counts are exact and sum to the number of rows you sent:

integer

Rows geocoded and staged.

integer

Rows with no address.

integer

Rows whose address couldn’t be geocoded.

Take import_id into the campaign wizard to build a reactivation campaign from the staged rows.

Status codes

Status	`error`	Meaning
`200`	—	Replay of a prior `Idempotency-Key`: the existing batch and its stored counts (nothing new created).
`201`	—	Batch staged.
`400`	`invalid_json`	Body isn’t valid JSON.
`401` / `403`	`Unauthorized`	Bad key / no org / missing `import:write`.
`409`	`import_in_progress`	The request that first used this `Idempotency-Key` is still processing. Retry after `Retry-After` seconds for its result.
`413`	`payload_too_large`	Body over 1 MB (declared or actual).
`422`	`invalid_payload`	Bad `source`, too many rows, or a bad field type/date; `detail` names the row.
`429`	`rate_limited`	Over 10 batches today. `Retry-After` = seconds to 00:00 UTC.
`502`	`geocoding_failed`	Geocoder error. Nothing imported; retry later.
`503`	`geocoding_unavailable` / `automations_disabled`	Geocoder down, or the platform kill switch (`Retry-After: 300`). Nothing imported; retry later.
`500`	`Internal server error`	Unexpected error.

On 429, 502, or 503, nothing was staged and no daily slot was consumed — retry the whole batch later.

Developer API

Endpoints

Request

Response

Status codes

​Request

​Response

​Status codes

Request

Response

Status codes