Email Sending API

Send transactional emails with HTML or plain text content via the Bismuth Email Sending API. Supports CC/BCC recipients and file attachments (base64-encoded, max 25MB per file). Emails are delivered using Resend and charged at $0.01 USDC per call.

Endpoints

Free test endpoint: GET /send/test at https://x402-email-api-production.up.railway.app — returns fixture data, no real email sent, no wallet required. Paid endpoint: POST /send — $0.01 USDC on Base per call.

No API key required

Add X402_PRIVATE_KEY to your MCP config to enable paid calls — each request automatically settles $0.01 USDC on Base. Use the free test endpoint to confirm the response schema before enabling payments.

Note

All emails are sent from x402 Email API <[email protected]>. The From address cannot be overridden. Use the reply_to field so recipients can respond to your address.

Parameters

Parameter	Type	Required	Default	Description
to	string	Yes	—	Recipient email address
subject	string	Yes	—	Email subject (max 998 characters, RFC 5321)
body	string	Yes	—	Email body — HTML or plain text (max 100 KB); HTML auto-detected
reply_to	string	No	—	Reply-to address for recipient responses
cc	string[]	No	—	CC recipients — list of email addresses
bcc	string[]	No	—	BCC recipients — list of email addresses
attachments	object[]	No	—	File attachments (see Attachments section below)

Attachment Object

Each attachment in the attachments array has the following fields:

Field	Type	Required	Description
filename	string	Yes	Filename including extension (e.g. report.pdf)
content	string	Yes	Base64-encoded file content (max 25MB decoded)
content_type	string	No	MIME type — auto-derived from filename if omitted

Caution

Attachment size is validated against the decoded byte length, not the base64 string length. Each file must be under 25MB before encoding. The content_type field is optional — if omitted, it is auto-derived from the filename extension.

Example — curl

# Free test (no wallet required — no real email sent)
curl https://x402-email-api-production.up.railway.app/send/test

# Paid call — basic email
curl -X POST https://x402-email-api-production.up.railway.app/send \
  -H "Content-Type: application/json" \
  -d '{"to": "[email protected]", "subject": "Hello from Bismuth", "body": "<h1>Hello</h1><p>Sent via Bismuth email API.</p>", "reply_to": "[email protected]"}'

# Paid call — email with CC, BCC, and attachment
curl -X POST https://x402-email-api-production.up.railway.app/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Q1 Report",
    "body": "<p>Please find the Q1 report attached.</p>",
    "cc": ["[email protected]"],
    "bcc": ["[email protected]"],
    "attachments": [{"filename": "report.pdf", "content": "JVBERi0xLjQ..."}]
  }'

Example — MCP Tool Call

“Send an email to [email protected] with the subject ‘Meeting Notes’, CC the team lead, and attach the PDF report.”

{
  "tool": "x402_send_email",
  "arguments": {
    "to": "[email protected]",
    "subject": "Meeting Notes",
    "body": "<h1>Meeting Notes</h1><p>Here are the notes from today's meeting.</p>",
    "reply_to": "[email protected]",
    "cc": ["[email protected]"],
    "attachments": [
      {
        "filename": "notes.pdf",
        "content": "JVBERi0xLjQ...",
        "content_type": "application/pdf"
      }
    ]
  }
}

Returns

On success, the API returns:

{
  "success": true,
  "message_id": "re_abc123xyz"
}

Field	Type	Description
success	boolean	true when the email was accepted for delivery
message_id	string	Resend message ID for delivery tracking

Rate Limits

Caution

Limited to 10 emails per day per wallet and 5 emails per day per wallet per recipient domain (including CC and BCC recipients). Both limits reset at midnight UTC.

Error Codes

Code	Meaning
402	Payment required — x402 handshake (handled automatically by MCP server)
422	Invalid email address, subject too long, body exceeds 100 KB, invalid base64 attachment, or attachment exceeds 25MB
429	Daily wallet limit (10/day), per-domain limit (5/day), or free test rate limit (100/hour per IP) exceeded
500	Email provider authentication error
503	Email provider quota exhausted or temporarily unavailable