NevarMail

Business contacts

Group your contacts by the business they work for, keep that in step with your own systems, and email them through lists.

Businesses organize who works where. To email them, add them to a list. Lists carry subscriptions and unsubscribes.

A business is a name, the domains its people use, and the people who work there. It lives in your contact storage beside your contacts, scoped to the project (or to your organization, if your contacts are shared across projects). Another NevarMail customer can have a business with the same domain; yours and theirs never mix.

In the app

Open Audience → Businesses. You need the safety.configure permission to see it, and contact storage turned on for at least one of your projects: until then the item isn't in the menu, and the page says contact storage isn't on yet. With several projects, the page offers only the ones that have contact storage.

  • Add a business with a name and, optionally, its domains (acme.com, acme.io). Consumer mail domains such as gmail.com are refused: anyone can have an address there, so they say nothing about where someone works.
  • Add people from acme.com (Add people from these domains when the business has more than one domain) adds every contact whose email is at one of the business's domains. It runs when you click it; contacts who arrive later join the next time you click it.
  • Add people adds one person by email. If they are not a contact yet, they become one.
  • Remove from business takes a person out of the business. They stay in Contacts and on every list they are on.

Deleting a business is done through the API. It removes the business and its memberships; every contact stays.

Emailing a business

A business is not a send target. To email its people, add them to a list; the list carries their subscriptions and unsubscribes, exactly like any other list.

From your code

Keep businesses in step with your own system using its id for the business (an external ref). The upsert is idempotent, so you can run it on every change.

import { NevarMail } from "@bernierllc/nevarmail";

const client = new NevarMail({ apiKey: process.env.NEVARMAIL_API_KEY! });

const { business, created } = await client.businesses.upsertByExternalRef("crm", "acct_123", {
  name: "Acme",
  domains: ["acme.com"],
});

created is true the first time and false after. Then add people with the business id it returned:

await client.businesses.members.add(
  business.id,
  { email: "ada@acme.com", firstName: "Ada" },
  { role: "owner", addedBy: "sync" },
);
await client.businesses.members.remove(business.id, "bo@acme.com");

Prefer plain HTTP? The same calls are the endpoints below. For example, with {system} as crm and {ref} as your account id:

curl -X PUT https://app.nevarmail.com/api/v1/businesses/by-ref/{system}/{ref} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme", "domains": ["acme.com"] }'
  • Keys need the contacts:write scope (contacts:read to list and read). A key bound to one project needs no projectId; an organization-wide key passes projectId (an option on every SDK call) to choose which project's businesses it means, when the organization has more than one project.
  • attributes merges into what is there; send null for a key to delete it.
  • Adding someone who is already a member changes nothing, unless you send a different role, which replaces the old one.
  • Up to 100 people per request, and up to 50 domains per business.
EndpointWhat it does
GET /api/v1/businessesList businesses, by name
POST /api/v1/businessesCreate a business
GET / PATCH / DELETE /api/v1/businesses/{id}Read, update or delete one
PUT /api/v1/businesses/by-ref/{system}/{ref}Create or update by your system's id
GET / POST / DELETE /api/v1/businesses/{id}/membersList, add or remove people
POST /api/v1/businesses/{id}/members/by-domainAdd people from the business's domains

The API reference lists every field.

Errors you may see

CodeMeaning
CONSUMER_DOMAINThe domain is a consumer mail domain.
BUSINESS_DOMAIN_TAKEN / BUSINESS_REF_TAKENAnother of your businesses already has that domain or external ref.
NO_DOMAINSAdding people from domains needs the business to have a domain.
BUSINESS_NOT_FOUNDNo business with that id in this project.
CONTACT_STORAGE_NOT_ENABLEDContact storage is not turned on for this project yet.
CONTACT_SCOPE_SWITCHINGYour organization is switching contact scope; retry shortly.

On this page