Pinal Developers

API reference

Mail

Messages, drafts and labels in Pinal Mail.

Base URL https://api.pinal.tech/v1

List messages

GET /mail/messages

Messages in a mailbox, newest first. With only mail.metadata, bodies and attachments are omitted.

Query parameters

  • label string

    Filter by label ID.

  • q string

    Search query, same syntax as Picacho's search bar.

  • limit integer

    Items per page, 1–100.

  • cursor string

    Opaque cursor from a previous page's next_cursor.

Responses

curl "https://api.pinal.tech/v1/mail/messages?label=inbox&q=from%3Asam%20has%3Aattachment" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response · 200
{
  "messages": [
    {
      "id": "msg_8f2c41",
      "thread_id": "string",
      "from": {
        "name": "string",
        "email": "alex@pinal.email"
      },
      "to": [
        {
          "name": "string",
          "email": "alex@pinal.email"
        }
      ],
      "cc": [
        {
          "name": "string",
          "email": "alex@pinal.email"
        }
      ],
      "subject": "string",
      "snippet": "string",
      "text": "string",
      "html": "string",
      "labels": [
        "string"
      ],
      "read": true,
      "attachments": [
        {
          "id": "string",
          "filename": "string",
          "size": 0,
          "content_type": "string"
        }
      ],
      "date": "2026-11-19T15:20:04Z"
    }
  ],
  "next_cursor": "string"
}

Send a message

POST /mail/messages

Sends immediately from the person's primary address. Flagged as a sensitive action on the consent screen.

Request body application/json

  • to array of Address required
  • cc array of Address
  • bcc array of Address
  • subject string required
  • text string
  • html string
  • in_reply_to string

    Message ID to reply to.

Responses

curl -X POST "https://api.pinal.tech/v1/mail/messages" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [
      {
        "email": "sam@example.com"
      }
    ],
    "subject": "Trail map",
    "text": "Here's the route for Saturday."
  }'
Response · 202
{
  "id": "msg_8f2c41",
  "thread_id": "string",
  "from": {
    "name": "string",
    "email": "alex@pinal.email"
  },
  "to": [
    {
      "name": "string",
      "email": "alex@pinal.email"
    }
  ],
  "cc": [
    {
      "name": "string",
      "email": "alex@pinal.email"
    }
  ],
  "subject": "string",
  "snippet": "string",
  "text": "string",
  "html": "string",
  "labels": [
    "string"
  ],
  "read": true,
  "attachments": [
    {
      "id": "string",
      "filename": "string",
      "size": 0,
      "content_type": "string"
    }
  ],
  "date": "2026-11-19T15:20:04Z"
}

Get a message

GET /mail/messages/{id}

One message with its body and attachment list.

Path parameters

  • id string required

    Message ID.

Responses

curl "https://api.pinal.tech/v1/mail/messages/{id}" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response · 200
{
  "id": "msg_8f2c41",
  "thread_id": "string",
  "from": {
    "name": "string",
    "email": "alex@pinal.email"
  },
  "to": [
    {
      "name": "string",
      "email": "alex@pinal.email"
    }
  ],
  "cc": [
    {
      "name": "string",
      "email": "alex@pinal.email"
    }
  ],
  "subject": "string",
  "snippet": "string",
  "text": "string",
  "html": "string",
  "labels": [
    "string"
  ],
  "read": true,
  "attachments": [
    {
      "id": "string",
      "filename": "string",
      "size": 0,
      "content_type": "string"
    }
  ],
  "date": "2026-11-19T15:20:04Z"
}

Label or mark a message

PATCH /mail/messages/{id}

Add or remove labels, or mark read/unread.

Path parameters

  • id string required

    Message ID.

Request body application/json

  • add_labels array of string
  • remove_labels array of string
  • read boolean

Responses

curl -X PATCH "https://api.pinal.tech/v1/mail/messages/{id}" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "add_labels": [
      "string"
    ],
    "remove_labels": [
      "string"
    ],
    "read": true
  }'
Response · 200
{
  "id": "msg_8f2c41",
  "thread_id": "string",
  "from": {
    "name": "string",
    "email": "alex@pinal.email"
  },
  "to": [
    {
      "name": "string",
      "email": "alex@pinal.email"
    }
  ],
  "cc": [
    {
      "name": "string",
      "email": "alex@pinal.email"
    }
  ],
  "subject": "string",
  "snippet": "string",
  "text": "string",
  "html": "string",
  "labels": [
    "string"
  ],
  "read": true,
  "attachments": [
    {
      "id": "string",
      "filename": "string",
      "size": 0,
      "content_type": "string"
    }
  ],
  "date": "2026-11-19T15:20:04Z"
}

Create a draft

POST /mail/drafts

Saves a draft the person can review and send from their mail app.

Request body application/json

  • to array of Address required
  • cc array of Address
  • bcc array of Address
  • subject string required
  • text string
  • html string
  • in_reply_to string

    Message ID to reply to.

Responses

curl -X POST "https://api.pinal.tech/v1/mail/drafts" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [
      {
        "name": "string",
        "email": "alex@pinal.email"
      }
    ],
    "cc": [
      {
        "name": "string",
        "email": "alex@pinal.email"
      }
    ],
    "bcc": [
      {
        "name": "string",
        "email": "alex@pinal.email"
      }
    ],
    "subject": "string",
    "text": "string",
    "html": "string",
    "in_reply_to": "string"
  }'
Response · 201
{
  "id": "msg_8f2c41",
  "thread_id": "string",
  "from": {
    "name": "string",
    "email": "alex@pinal.email"
  },
  "to": [
    {
      "name": "string",
      "email": "alex@pinal.email"
    }
  ],
  "cc": [
    {
      "name": "string",
      "email": "alex@pinal.email"
    }
  ],
  "subject": "string",
  "snippet": "string",
  "text": "string",
  "html": "string",
  "labels": [
    "string"
  ],
  "read": true,
  "attachments": [
    {
      "id": "string",
      "filename": "string",
      "size": 0,
      "content_type": "string"
    }
  ],
  "date": "2026-11-19T15:20:04Z"
}

List labels

GET /mail/labels

System and custom labels with unread counts.

Responses

curl "https://api.pinal.tech/v1/mail/labels" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response · 200
{
  "labels": [
    {
      "id": "inbox",
      "name": "string",
      "system": true,
      "unread": 0,
      "color": "string"
    }
  ]
}