Leads
| Method | Path | Description |
|---|---|---|
GET | /leads | List leads, newest first. Query: page, limit (max 200), q, verificationStatus, espClass, tagId. The order is fixed, so paging through all pages returns every lead exactly once |
POST | /leads | Bulk create/update up to 1,000 leads (merges by email) |
PATCH | /leads/:id | Update one lead’s fields |
PATCH | /leads/bulk | Update up to 1,000 leads, each found by id or email. Returns updated, unchanged, notFound |
POST | /leads/bulk-delete | Permanently delete up to 1,000 leads by id (owner/admin). Body: leadIds. Returns deleted |
POST | /leads/:leadId/tags | Attach a tag to a lead |
DELETE | /leads/:leadId/tags/:tagId | Remove a tag from a lead |
A lead that was emailed or replied can be deleted too. Its replies go with it; the emails sent to it are kept (they count for mailbox daily limits, plan quota and bounce health).
Create/update leads
curl -X POST https://api.sendboxes.tech/leads \
-H "Authorization: Bearer sb_live_..." -H "Content-Type: application/json" \
-d '{
"leads": [
{ "email": "[email protected]", "firstName": "Jane", "companyDomain": "example.com" }
]
}'Lead fields: email (required), firstName, lastName, companyDomain, companyName,
phoneNumber, jobTitle, timezone, customFields (a flat string-keyed object — every key is
usable as a {{token}} in a sequence step).
An email already suppressed on your suppression list is skipped, not
rejected — the response reports how many were created, updated and suppressed.
The response also has leads: one { email, id, status } per lead (status is created or
updated), in the order you sent them. Match ids to your input by email. leadIds is the
same list of ids in the same order. Suppressed emails are listed in suppressedEmails and get no id.
Merge: if the email already exists, only the fields you send change; fields you leave out
keep their value. "" clears a field. customFields are merged key by key (send
{ "city": "NYC" } and the lead’s other custom fields stay). The same rules apply to
PATCH /leads/bulk.
timezone must be an IANA zone (e.g. America/New_York, see GET /timezones). On POST /leads
an unknown zone is skipped for that lead and listed in warnings; the lead is still saved. On
PATCH it is rejected with a 400.
Email verification
Every lead is verified automatically in the background shortly after it is created (a syntax check
plus an MX lookup — no email is sent). A lead starts at verificationStatus: "UNKNOWN" and moves to
one of VALID, INVALID_SYNTAX, NO_MX_RECORD, DISPOSABLE, or UNKNOWN_ERROR. Filter the list
by it: GET /leads?verificationStatus=VALID. Verification does not block anything — an unverified
(UNKNOWN) lead is still usable and can be added to a campaign; the status is informational.
Verifications are metered by your plan’s monthly email-validation allowance. Once that allowance is
used up for the calendar month, further leads stay UNKNOWN until the next month or a plan upgrade
(they are still created and usable).