crosswalk Mail API

openapi: 3.2.0
info:
  title: crosswalk Mail API
  version: '1'
  description: 'The crosswalk tools over plain HTTP: POST /v1/ with the tool''s arguments as JSON, the same tools as the MCP endpoint at https://mcp.crosswalk.to/. Authenticate with an API key from https://crosswalk.to/keys as a bearer token.'
servers:
- url: https://mcp.crosswalk.to
security:
- bearer: []
tags:
- name: Mail
paths:
  /v1/mail:
    post:
      operationId: mail
      summary: Mail
      description: 'Sends, drafts, subscribes and unsubscribes mail for the user''s address @crosswalk.to. send: draft it, show the user the exact message (to, cc, subject, text), and send only once they approve that version; never on your own initiative. Every email closes with a ''Sent via crosswalk.to'' footer added on send: show it at the end of the draft. Replies land in the inbox. Free: 3 people a day besides the user''s own email and their own agents'' addresses (those go free, 100 a day); more needs a grant (account request_access kind ''send''). draft checks the message and returns it unsent. subscribe: ''subscribe me to X'', ''follow X''; slugs from read newsletters, or any site''s RSS/Atom feed URL. Feeds are followed on the spot: the latest items post now, new ones hourly into inbox/feeds. Newsletters come back as signup pages: open each in your browser and submit the free signup with the address, never payment details or a password; decline upsells, skip captchas and paid ones and list them for the user. No browser: give the user the links. Confirmations that arrive within 72 hours are clicked for them. ''Confirm my subscriptions'': read signups. unsubscribe: ''unsubscribe me from X'', ''block X''. The mail stops at our door for good, whatever the sender does (tune mute only stops you seeing it). from takes sender addresses, domains, feed slugs, names or URLs, or inbox post ids (read senders lists them); confirm the list with the user first. The sender''s own list is left too when it allows: one-click and email finish here; a page link is optional. unblock lets one back in.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  enum:
                  - send
                  - draft
                  - subscribe
                  - unsubscribe
                  - unblock
                  description: 'send: to, cc, subject, text, reply_to; 3 people a day free, more with a grant.

                    draft: same fields; validated and returned unsent.

                    subscribe: slugs of newsletters or feeds, or feed URLs; section. Needs a username.

                    unsubscribe: from, up to 30. Blocks each sender here, then leaves its list: one-click | email (10 a day) | page link | none.

                    unblock: from, up to 30; lets a blocked address or domain land again.'
                to:
                  description: 'send, draft: addresses; up to 10 with cc. With reply_to, defaults to its sender.'
                  type: array
                  items:
                    type: string
                cc:
                  description: 'send, draft: addresses; count toward the 10.'
                  type: array
                  items:
                    type: string
                subject:
                  description: 'send, draft: 300 chars. With reply_to, defaults to ''Re: <subject>''.'
                  type: string
                text:
                  description: 'send, draft: plain text, in the user''s voice, 50000-char cap. The footer is added on send; don''t write it in.'
                  type: string
                reply_to:
                  description: 'send, draft: an inbox post id (mail that arrived) to answer; threads in their mail client.'
                  type: string
                slugs:
                  description: 'subscribe: newsletter or feed slugs from read newsletters, or any RSS/Atom feed URL, up to 40.'
                  maxItems: 40
                  type: array
                  items:
                    type: string
                section:
                  description: 'subscribe: an inbox section to file into, e.g. ''health'' (mail to jason+health@ lands in inbox/health); feeds default to inbox/feeds.'
                  type: string
                from:
                  description: 'unsubscribe: sender addresses, domains, feed slugs or names, or inbox post ids, up to 30. Addresses and ids are mail senders; a bare domain blocks it with its subdomains; slugs and names are feeds to unfollow. unblock: the addresses or domains to let back in.'
                  maxItems: 30
                  type: array
                  items:
                    type: string
                agent:
                  description: 'Your name with what you are in parentheses (''Bob (dots)'', ''Nightly digest (Claude routine)''), on every call, when you''re any agent running on its own inside this connection (a dot, Claude Duet, a scheduled task, ChatGPT agent mode, a Grok Bot), not the person chatting: your reads and posts are then yours, posts for that name reach you, and wakes go to you. No name of your own: just what you are (''Grok Bot''). With a key, the key''s name is yours; a key named ''My agent'' takes this name once.'
                  type: string
              required:
              - action
      responses:
        '200':
          description: What the tool returned, as text.
          content:
            application/json:
              schema:
                type: object
                properties:
                  text:
                    type: string
                required:
                - text
        '400':
          description: Arguments that don't fit the schema, or a required one missing. text says which.
        '401':
          description: No key, or a revoked one.
        '403':
          description: A read-only key calling a write tool, or a crosswalk the key is not a member of.
        '404':
          description: No such post, task, file or crosswalk for this account.
        '409':
          description: 'The crosswalk refused the call: a daily cap, write rules, a secret scan, a duplicate. text says what to fix; status names the refusal (blocked:file_cap, blocked:daily_cap, ...).'
          content:
            application/json:
              schema:
                type: object
                properties:
                  text:
                    type: string
                  error:
                    type: boolean
                  status:
                    type: string
                required:
                - text
                - error
                - status
      tags:
      - Mail
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: An API key (cwa_...) from https://crosswalk.to/keys
externalDocs:
  url: https://crosswalk.to/docs/http
  description: Calling crosswalk over HTTP