Contacts and lists

Every contact says where consent came from

consent is required on every call that creates a contact, and there is no default. It is recorded on the contact as consentSource, with consentAt set to when it was first stored.

Re-importing somebody who is already a contact keeps their original consent record. How a person came to be in your book does not change because a spreadsheet mentioned them again.

Whether a contact can be mailed is the suppression list’s answer

A contact carries no “subscribed” flag of its own. suppressed and suppressionReasons are read from your suppression list every time you fetch a contact, so an unsubscribe or a hard bounce shows up the moment it happens and a contact can never disagree with what a send would actually do.

suppressed is true when a send to the address would be refused on some stream — an unsubscribe from announcements shows here even though the same person still receives your password resets. The reasons are the suppression reasons: hard_bounce, complaint, unsubscribe and the rest.

Deleting a contact does not remove a suppression. Deleting somebody who unsubscribed and importing them again next month must not be a way to mail them again, so it is not.

Fields are merge fields

fields is an object of your own values — a plan name, a region, a first name — that a broadcast can put into its content as {{plan}}. Alongside them every contact always has {{email}}, and {{name}} when it has a name. Those two win over a field of the same name.

How the values are used at send time — and what happens when a contact is missing one — is on the broadcasts page.

Add a contact

const contact = await posthaste.contacts.create({
  email: user.email,
  name: user.name,
  fields: { plan: user.plan },
  // Where permission to mail this person came from. Required, no default.
  consent: 'signed_up',
})

contact.id // 'con_…'
contact.suppressed // read from the suppression list, not stored here

// An address already in your contacts is refused with 409 contact_exists,
// so a retry after a lost response cannot leave a duplicate behind.

Import

Up to 1,000 rows per call, merged by address. One consent applies to the whole call, and an optional list puts every row on that list — new and existing contacts alike. The dashboard reads a CSV and sends it in chunks of this size.

// A thousand rows per call. Chunk a larger file and send the chunks in turn.
for (let i = 0; i < rows.length; i += 1000) {
  const result = await posthaste.contacts.import({
    consent: 'customer',
    list: listId,
    contacts: rows.slice(i, i + 1000),
  })
  // Indexes in `invalid` are into THIS chunk, not the whole file.
  report(i, result.invalid)
  if (result.overLimit > 0) break // the plan is full; the rest would be counted too
}

The same address twice in one call is one contact. The first spelling of the address stands, and a later row’s name and fields are added to it.

Read, change and delete

Newest first, keyset-paginated — see pagination. limit is 1–200 (default 50), before is the nextCursor from the previous page, search matches anywhere in the address or the name, and list narrows to one list. total is every contact on the account whatever the filters — the number your plan counts.

curl -G https://api.posthastemail.dev/v1/contacts \
  -H "authorization: Bearer $POSTHASTE_KEY" \
  --data-urlencode "list=lst_AZLm3kQ8T2Sf9pXbNc7HrQ" \
  --data-urlencode "search=example.com" \
  --data-urlencode "limit=100"

# 200
# {
#   "data": [ { "id": "con_…", "email": "…", "suppressed": true,
#               "suppressionReasons": ["unsubscribe"], … } ],
#   "hasMore": false,
#   "nextCursor": null,
#   "total": 1840
# }

One contact, with a lists array of the lists it is on.

Changes name (send null to clear it) and fields. fields replaces the whole set — send the ones you want to keep. The address is the identity and cannot be changed: delete the contact and add the new address.

204. Removes the contact from your book and from every list. It leaves the suppression list alone.

Lists

A list is a named group of contacts, and it is what a broadcast is sent to. A contact can be on any number of lists; deleting a list removes the grouping, never the contacts.

A list has a name (1–80 characters, unique on your account ignoring case — a clash is 409 name_taken) and an optional description of up to 500. Every list comes back with its memberCount. GET /v1/lists returns them all, alphabetically, in one response.

Adding members takes up to 1,000 con_ ids and is idempotent: a contact already on the list is counted in alreadyMembers, and an id that names no contact on your account comes back in notFound rather than failing the others. Removing a member takes it off the list and leaves it in your book.

const list = await posthaste.lists.create({
  name: 'Status updates',
  description: 'Everyone on a paid plan',
})

// Existing contacts, by id. Idempotent: already-members are counted, not refused.
const { added, alreadyMembers, notFound } = await posthaste.lists.addMembers(list.id, [
  'con_Kd93Lm2PqR7tUv5WxY1zAb',
  'con_7Qw2Er4Ty6Ui8Op0As1Df3',
])

// Everybody on it, every page.
for await (const contact of posthaste.contacts.autoPaginate({ list: list.id })) {
  contact.email
}

The contacts:read and contacts:write scopes cover lists too.

Plan limits

How many contacts you may keep: Free 500, Starter 5,000, Growth 50,000, Scale 250,000, Enterprise unlimited. How many lists: Free 2, Starter 10, Growth 50, Scale unlimited, Enterprise unlimited. Past either, a create is 403 with contact_limit_reached or list_limit_reached, carrying the limit and how many you have; an import is not refused, and counts the rows that did not fit in overLimit. A list cannot hold more people than your book does, so there is no separate limit on recipients per broadcast. The full grid is in limits.