Contacts & groups

Required permission: Contacts → Read to list, Contacts → Write to create, edit or delete.

These are organization contacts. A key never sees anybody’s personal address book.Contacts a person adds in the web app belong to that person and are invisible to every API key — as are their groups. Contacts a key creates are visible to your team in the dashboard, because an address book nobody can reach is not an address book.

Who just emailed me?

The reason this endpoint is worth having. Pair it with the message.received webhook and one call turns a sender into a person:

curl "https://app.ruber.me/api/v1/contacts?email=billing@supplier.com" \
  -H "Authorization: Bearer $RUBER_API_KEY"

The address is matched case-insensitively, so the value straight out of a webhook payload works without cleaning it up first.

List contacts

GET https://app.ruber.me/api/v1/contacts

Parameter
`email`	Exact address match, case-insensitive.
`search`	Matches name and organisation.
`limit`	1–200. Defaults to 50.
`page`	0-based.

{
  "data": [
    {
      "id": "68835c58-f872-4bdc-b87d-537f56252a79",
      "display_name": "Alice Chen",
      "given_name": "Alice",
      "family_name": "Chen",
      "organisation": "Acme",
      "job_title": "Head of Billing",
      "emails": [{ "label": "Work", "value": "alice@acme.com" }],
      "phones": [{ "label": "Mobile", "value": "+44 7700 900000" }],
      "websites": [],
      "addresses": [],
      "custom": [],
      "birthday": "--04-01",
      "colour": "slate",
      "starred": false,
      "has_photo": false,
      "created_at": "2026-09-09T13:34:04.739Z",
      "updated_at": "2026-09-09T13:34:04.739Z"
    }
  ],
  "total": 1,
  "page": 0,
  "has_more": false
}

search deliberately does not read notes. A search that reaches into free text turns a lookup into a way to read the whole address book by fishing for words. Name and organisation are what a lookup is for.

Create a contact

POST https://app.ruber.me/api/v1/contacts

curl -X POST https://app.ruber.me/api/v1/contacts \
  -H "Authorization: Bearer $RUBER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Alice Chen",
    "organisation": "Acme",
    "emails": [{ "label": "Work", "value": "Alice@Acme.com" }]
  }'

display_name is the only required field.

Field
`display_name`	required	Up to 200 characters.
`given_name`, `middle_name`, `family_name`, `nickname`		Up to 100 each.
`organisation`, `job_title`		Up to 200 each.
`pronouns`		Up to 60.
`birthday`		`YYYY-MM-DD`, or `--MM-DD` when the year is unknown.
`emails`		Up to 20 `{label, value}`. Each `value` must be a real address.
`phones`, `custom`		Up to 20 each.
`websites`, `addresses`		Up to 10 each.
`notes`		Up to 8,000 characters.
`colour`		`slate`, `red`, `amber`, `green`, `blue`, `violet`, `pink`.
`starred`		Boolean.

Addresses are stored lowercased and trimmed, which is what makes ?email= match. Empty rows are dropped rather than stored — an empty row is somebody leaving a field alone, not an error.

Read, replace, delete

GET    /v1/contacts/{id}
PATCH  /v1/contacts/{id}
DELETE /v1/contacts/{id}

PATCH replaces the whole contact; it does not merge. A field you leave out is cleared.Sending {"display_name": "Alice Chen"} to a contact that had an email address leaves it with no email address — and it will then stop appearing in ?email= lookups. Read the contact, change what you want, and send it back whole.The one exception is the photograph, which is never touched by a write, so replacing a record cannot silently remove somebody’s picture.

Groups

GET    /v1/contact-groups
POST   /v1/contact-groups
PATCH  /v1/contact-groups/{id}
DELETE /v1/contact-groups/{id}

{
  "id": "d2f3b653-3456-41f1-b82c-5e2f33962b8f",
  "name": "Suppliers",
  "colour": "green",
  "member_count": 2,
  "members": ["68835c58-…", "9a71bd02-…"],
  "created_at": "2026-09-09T13:35:00.539Z",
  "updated_at": "2026-09-09T13:35:00.539Z"
}

Field
`name`	required	Up to 80 characters, unique in the organization.
`colour`		A named colour, or a hex code like `#3b82f6`.
`members`		Contact ids. Omit to leave membership alone.

Membership travels with the group rather than living at its own endpoint: a group is small, and “the group is these contacts” is one fact — splitting it across two calls would let a caller leave a group half-updated with no way to tell.

members omitted means “leave it alone”; members: [] means “empty it”. That distinction is what lets a rename be only a rename.Every id must be a contact in your organization. One that is not — including a member’s personal contact — is refused with 400, and the group is not created or changed. Nothing is half-applied.

Deleting a group removes the grouping and keeps the contacts. A group is a label on people, not a container of them.

Not available yet

Contact activity and correspondents. The web app shows how often you have written to somebody and who else was involved. Both are computed from an index that is only refreshed when a person opens the app, and that is keyed to that person — so an API version would return figures that are quietly out of date and incomplete. It is left out rather than shipped wrong. Photographs. has_photo tells you one exists. Fetching it is not supported: the app serves photographs from a session-authenticated route, and the alternative — a direct storage URL — would make every contact’s picture readable by anyone who guessed the address.

Errors

Code	HTTP	Cause
`invalid_request`	`400`	Missing `display_name`, a bad email or birthday, a field over its limit, a duplicate group name, or a member id that is not yours.
`unauthorized`	`401`	Missing, malformed, unknown or revoked key.
`forbidden`	`403`	The key lacks `contacts:read` or `contacts:write`.
`not_found`	`404`	No organization contact or group with that id. A personal one answers the same way.
`rate_limited`	`429`	Over 600 requests in a minute.

See Errors for the full response shape.

Start here

Using Ruber

API

Mail clients

Contacts & groups

Who just emailed me?

List contacts

Create a contact

Read, replace, delete

Groups

Not available yet

Errors

​Who just emailed me?

​List contacts

​Create a contact

​Read, replace, delete

​Groups

​Not available yet

​Errors

Who just emailed me?

List contacts

Create a contact

Read, replace, delete

Groups

Not available yet

Errors