curl -X POST 'https://api.mails.ai/v1/threads/thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E/notes' \
  -H "Authorization: Bearer $MAILS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "body": "Customer called about this one." }'

mails threads notes add thrd_01JABC "Asked finance about the refund. Waiting to hear back."

{
  "name": "mails_add_thread_note",
  "arguments": {
    "thread_id": "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
    "body": "Customer called about this one."
  }
}

{
  "id": "note_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "object": "<object>",
  "thread_id": "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "body": "<body>",
  "author": {
    "kind": "user",
    "id": "usr_01JZX8K3M9Q4P7VN2YB6RTDC0E",
    "email": "jordan@example.com",
    "name": "<name>"
  },
  "created_at": "2026-10-04T12:00:00.000Z"
}

201  The note.
400  Invalid request — malformed JSON or a field failed
     validation. Also feature_not_enabled when this
     server has a feature switched off (custom domains
     before they are available).
401  Missing or invalid API key.
403  The API key lacks the required scope
     (insufficient_scope), or the token belongs to an
     app connected by sign-in and this operation is
     closed to connected apps
     (connected_app_not_allowed).
404  Resource not found in this workspace, or the agent
     a send names is archived (agent_archived).
409  Conflict — duplicate resource, an in-progress
     idempotent request, a draft or scheduled message
     that started sending while it was being changed, or
     a thread deleted for good while one of its messages
     is being sent (duplicate_resource); or an agent
     name more than one agent has (agent_name_conflict:
     use the agent's id); or a status change on an
     archived agent, since archiving cannot be undone
     (agent_archived).
422  Unprocessable — agent paused, recipient suppressed,
     a recipient at test.mails.ai other than
     reply@test.mails.ai (unknown_test_address), or
     abuse guard.
500  Internal server error.

Add a note to a thread

A note for the team: 1 to 10,000 characters, never sent to anyone.

POST/v1/threads/{id}/notesscope · manage

curl -X POST 'https://api.mails.ai/v1/threads/thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E/notes' \
  -H "Authorization: Bearer $MAILS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "body": "Customer called about this one." }'

mails threads notes add thrd_01JABC "Asked finance about the refund. Waiting to hear back."

{
  "name": "mails_add_thread_note",
  "arguments": {
    "thread_id": "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
    "body": "Customer called about this one."
  }
}

{
  "id": "note_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "object": "<object>",
  "thread_id": "thrd_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "body": "<body>",
  "author": {
    "kind": "user",
    "id": "usr_01JZX8K3M9Q4P7VN2YB6RTDC0E",
    "email": "jordan@example.com",
    "name": "<name>"
  },
  "created_at": "2026-10-04T12:00:00.000Z"
}

201  The note.
400  Invalid request — malformed JSON or a field failed
     validation. Also feature_not_enabled when this
     server has a feature switched off (custom domains
     before they are available).
401  Missing or invalid API key.
403  The API key lacks the required scope
     (insufficient_scope), or the token belongs to an
     app connected by sign-in and this operation is
     closed to connected apps
     (connected_app_not_allowed).
404  Resource not found in this workspace, or the agent
     a send names is archived (agent_archived).
409  Conflict — duplicate resource, an in-progress
     idempotent request, a draft or scheduled message
     that started sending while it was being changed, or
     a thread deleted for good while one of its messages
     is being sent (duplicate_resource); or an agent
     name more than one agent has (agent_name_conflict:
     use the agent's id); or a status change on an
     archived agent, since archiving cannot be undone
     (agent_archived).
422  Unprocessable — agent paused, recipient suppressed,
     a recipient at test.mails.ai other than
     reply@test.mails.ai (unknown_test_address), or
     abuse guard.
500  Internal server error.

Path Parameters

idstringrequired

Thread id (thrd_…).

Body Parameters

bodystringrequired

The note, 1 to 10,000 characters. Only your team sees it: it is never sent, quoted in a reply or forward, or put in an event.

Emits thread.note_added, which says who wrote it but not what it says. A thread holds up to 500 notes (409 resource_cap_exceeded past that). A test key cannot add one to a thread holding live mail (403 live_mode_required).

Response

idstring

Note id (note_…).

objectstring

Always note.

thread_idstring

The thread (thrd_…) the note is on.

bodystring

What the note says, as written. Only the workspace sees it: a note is never sent, never quoted in a reply or forward, and never carried by an event or a webhook.

authorobject

Show propertiesHide properties

kindstring

user for a member signed in to the dashboard, key for an API key or an app connected by sign-in.

One of: user, key

idstring | null

The member's user id (usr_…), the API key's id (key_…) or connected app's id. Null for a member whose account has since been erased.

emailstring

The member's email. Only when kind is user and the member's account still exists.

namestring | null

The member's name, null when they have not given one. Only when email is there.

created_atstring

When the note was added (UTC).

Was this page helpful?