# How to Automate Etsy Customer Messages using the API - Tool: API Automations - Difficulty: Advanced - Fix time: 1-2 hours - Compatibility: Etsy v3 API; approved app with transactions_r scope; OAuth 2.0 with PKCE; external ESP for email delivery - Last updated: May 2026 ## TL;DR Etsy v3 API has no customer messaging endpoint — there is no `sendMessage` call. Instead, use the `order.paid` webhook (released late 2025) to detect new orders in real time, fetch order details via `GET /shops/{shop_id}/receipts/{receipt_id}`, then send personalized post-purchase emails through an external ESP (SendGrid, Resend). Every API request requires both `Authorization: Bearer ` AND `x-api-key: ` headers. Rate limit: 10 req/sec, 10,000 req/day. ## Best practices - Accept that there is no Etsy messaging API — design your workflow around external email delivery from the start. - Always include both Authorization: Bearer and x-api-key headers on every request — missing x-api-key is the most common integration failure. - Implement automatic token refresh: access tokens expire in 1 hour, so build refresh logic into your API wrapper before hitting the first expiry. - Always divide Etsy monetary values by their divisor — `amount: 2999, divisor: 100` = $29.99. Never display raw amounts. - Use the order.paid webhook (2025 addition) instead of polling receipts — webhooks are real-time and consume zero daily API quota. - Store processed receipt IDs to prevent sending duplicate emails — webhooks can be delivered more than once. - Request Commercial access early if your app will serve multiple sellers — the review takes days to weeks and is the critical path. - Apply for buyer_email permission separately — without it, receipt data contains buyer user IDs but not email addresses. ## Frequently asked questions ### Does the Etsy API have an endpoint to send messages to buyers? No. Etsy v3 API has no messaging or conversation endpoint. Etsy's internal messaging system is completely separate from the public API and is not accessible programmatically. The workaround is to use the order.paid webhook to detect new orders, fetch buyer details via getShopReceipts (including email if you have buyer_email permission), and send communications through an external ESP like SendGrid or Resend. This produces the same result as an Etsy message but delivered via email. ### Why does every Etsy API request need two authentication headers? Etsy's v3 API requires both `Authorization: Bearer ` (the OAuth 2.0 token proving the user authorized your app) AND `x-api-key: ` (your app's API key identifying which application is making the call). Omitting either header returns 401. This is non-standard but required by Etsy's architecture. Build both into every API request wrapper from the start. ### What is PKCE and why does Etsy require it? PKCE (Proof Key for Code Exchange, RFC 7636) is an OAuth 2.0 security extension that prevents authorization code interception attacks. You generate a random code_verifier (43-128 chars), compute code_challenge = base64url(SHA256(verifier)), include the challenge in the authorization URL, and include the original verifier when exchanging the code for tokens. Etsy makes PKCE mandatory on every authorization flow — unlike Google or GitHub where it's optional. ### How do I get the buyer's email address from Etsy orders? Buyer email access requires two things: the `transactions_r` scope AND a separate `buyer_email` permission approval from Etsy. With only `transactions_r`, you get the buyer's user ID but not their email. To request buyer_email access, submit an application through the Etsy Developer Portal explaining your use case. Until approved, you can use the buyer's name from the receipt for personalization but cannot email them directly. ### What is the Etsy webhook payload structure for order.paid? Etsy's order.paid webhook payload is intentionally minimal: `{ shop_id: 12345678, fetch_url: 'https://api.etsy.com/v3/application/shops/12345678/receipts/9876543' }`. You receive the shop ID and a pre-built URL pointing to the receipt — you still need to make a separate API call to get buyer details, line items, and totals. The webhook reduces but does not eliminate API calls. ### Is the Etsy API free? The Etsy API is free for personal access (up to 5 shops you own or that grant you access). For commercial use serving arbitrary sellers' shops, you need to request 'Commercial Access' which is manually reviewed. Commercial access is free — there are no usage fees — but new apps start at lower rate limits (5 req/sec, 5,000/day) until approved for the full 10 req/sec / 10,000/day tier. ### Can RapidDev help build a custom Etsy post-purchase communication system? Yes. RapidDev has built 600+ apps including Etsy seller tools that handle the full PKCE OAuth flow, webhook verification, receipt data processing, and ESP integration. We navigate the buyer_email permission process and build the polling fallback for pre-webhook compatibility. Book a free consultation at rapidevelopers.com. --- Source: https://www.rapidevelopers.com/api-automations/how-to-automate-etsy-customer-messages-using-the-api © RapidDev — https://www.rapidevelopers.com/api-automations/how-to-automate-etsy-customer-messages-using-the-api