Because the recipient list holds addresses, it also requires
contacts:read. An app or an AI assistant acts as the person who connected it and, with the View surveys and results permission, reads the sends of the surveys that person’s role reaches. An API key reads every send of the organization.
List sends
GET /email/sends takes a view:
past(the default) lists every send that isn’t waiting for a later time, newest first.scheduledlists the sends that wait for their time, soonest first.attentionlists the sends that failed or stopped in the last 30 days.
surveyId keeps one survey’s sends, and search matches part of the subject, the survey’s name or a list’s name, up to 200 characters. sort takes when, survey, recipients or answered, with :asc or :desc, such as recipients:desc. Because scheduled sends haven’t gone out, the scheduled view doesn’t offer answered as a sort.
audience.contactIds is null in the list. GET /email/sends/{sendId} fills it with the hand-picked people who are still contacts, by ID only, and GET /contacts/{contactId} reads their addresses with contacts:read.
Read who a send reached
GET /email/sends/{sendId}/recipients lists each recipient, oldest first:
statusissent,failed,bounced,complained, or a skipped reason:skipped_unsubscribed,skipped_dedup(the person had this survey before),skipped_suppressed,skipped_quota,skipped_pausedorskipped_survey_closed.- The
statusfilter takesall,sent,failed,bounced,complainedorskipped, which keeps every skipped reason. searchmatches part of the address, andsorttakestime,emailorstatus, with:ascor:desc.emailisnullonce the contact was deleted or erased, because Usertick blanks the address in the send history and keeps the row so the send’s counts stay.
GET /email/sends/{sendId}/recipients/summary counts every recipient of the send by status, without addresses, and groups the failed ones by error text. It returns the 50 most common texts, with failureReasonTotal giving how many different texts there are.
Errors
A send that isn’t your organization’s, or whose survey your role doesn’t reach, returns404 with PUB-014-001. A surveyId that isn’t one of your surveys returns 404 with APK-006-005. A sort, a view or a filter value the list doesn’t take returns 400 with PUB-001-004 for that parameter. See Errors.