# Instant sandbox: try the API with no account

HTML: https://www.app2email.com/docs/api/account-management/create-sandbox · Index: https://www.app2email.com/docs/api/llms.txt

`POST https://api.app2email.com/v1/account/sandbox`

No key, no body, no person. Answers an instant sandbox key (a2es_..., valid 7 days) for app2email's demo number +12025550100, where pretend customers answer and nothing reaches WhatsApp. Send the key as Authorization: Bearer on `base_url` (GET /me, GET /templates, POST /messages, GET /messages, GET /conversations, PUT /conversations/{contact}/owner, GET /events, and POST /sandbox/inbound to make a pretend customer write) or on the MCP server. Requests, answers, errors and events have the shapes of the real API, and templates are checked by the same code. Each key has its own state, kept in memory for 24 hours after the last call. Any other call there answers 403 not_in_instant_sandbox. Limit: 10 keys an hour per address.

|  |  |
| --- | --- |
| Scope | any valid key |
| MCP tool | `create_sandbox` on https://api.app2email.com/mcp |

## Responses

| Status | Meaning | error.code |
| --- | --- | --- |
| 200 | The key (shown once), the demo number, the pretend customers and the first calls to make. |  |
| 429 | A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. | `monthly_limit_reached`, `too_many_messages_to_recipient`, `whatsapp_rate_limit`, `rate_limited`, `daily_cap_reached`, `monthly_cap_reached`, `too_many_tests`, `register_limit_reached`, `too_many_signups`, `media_lookups_paused`, `too_many_invites` |
| 500 | Unexpected error on app2email's side. | `internal_error`, `background_start_failed`, `schedule_failed`, `shop_failed` |
| 503 | app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. | `whatsapp_connection_problem`, `whatsapp_number_not_registered`, `request_log_unavailable`, `whatsapp_unavailable`, `whatsapp_maintenance`, `block_list_busy`, `account_service_unavailable`, `sandbox_unavailable`, `partner_service_unavailable`, `shop_not_ready`, `submit_not_ready` |

### 200

```json
{
  "success": true,
  "request_id": "s4ndb",
  "instant_sandbox": {
    "api_key": "a2es_000qlA9iTHS1NETB9JExampleExampleExampleExampleExampleExampleExampleExampleExampleExampleExample0",
    "expires": "2026-11-22T03:00:00.000Z",
    "number": "12025550100",
    "base_url": "https://api.app2email.com/v1/12025550100",
    "mcp_url": "https://api.app2email.com/mcp",
    "authorization": "Authorization: Bearer <api_key>",
    "what_it_is": "A demo WhatsApp number with pretend customers. Requests and answers have the shapes of the real API; nothing reaches WhatsApp, and nobody else sees this key's messages. Its state lives in memory for 24 hours after the last call.",
    "test_contacts": [
      {
        "number": "12025550101",
        "name": "Ava",
        "behaviour": "answers every message a few seconds later"
      },
      {
        "number": "12025550102",
        "name": "Ben",
        "behaviour": "reads, never answers: a free-form message to him is 422 outside_24h_window"
      },
      {
        "number": "12025550103",
        "name": "Cara",
        "behaviour": "delivery fails: message.status failed and message.failed"
      },
      {
        "number": "12025550104",
        "name": "Dan",
        "behaviour": "answers STOP: contact.opted_out, then a marketing template to him is 403 recipient_opted_out"
      },
      {
        "number": "12025550105",
        "name": "Eve",
        "behaviour": "asks for a person: set the conversation's owner to human"
      }
    ],
    "templates": [
      "hello_world (en_US, UTILITY)",
      "order_update (en, UTILITY)",
      "weekend_offer (en, MARKETING)"
    ],
    "calls": [
      "GET /me",
      "GET /templates",
      "POST /messages",
      "GET /messages",
      "GET /conversations",
      "GET /conversations/{contact}",
      "PUT /conversations/{contact}/owner",
      "GET /events",
      "POST /sandbox/inbound"
    ],
    "try_first": [
      {
        "step": 1,
        "call": "GET https://api.app2email.com/v1/12025550100/templates",
        "why": "each template comes with a complete example_request"
      },
      {
        "step": 2,
        "call": "POST https://api.app2email.com/v1/12025550100/messages",
        "body": {
          "to": "12025550101",
          "type": "template",
          "template": {
            "name": "order_update",
            "language": {
              "code": "en"
            },
            "components": [
              {
                "type": "body",
                "parameters": [
                  {
                    "type": "text",
                    "text": "Ava"
                  },
                  {
                    "type": "text",
                    "text": "#1234"
                  }
                ]
              }
            ]
          }
        },
        "why": "Ava answers a few seconds later"
      },
      {
        "step": 3,
        "call": "GET https://api.app2email.com/v1/12025550100/events?wait=25",
        "why": "message.status sent, delivered, read, then message.received with Ava's answer. Pass the answer's cursor as ?after= on the next call"
      },
      {
        "step": 4,
        "call": "POST https://api.app2email.com/v1/12025550100/messages",
        "body": {
          "to": "12025550101",
          "type": "text",
          "text": {
            "body": "It arrives on Friday."
          }
        },
        "why": "a free-form reply: allowed because Ava wrote in the last 24 hours"
      }
    ],
    "not_here": "Webhooks (use GET /events), media uploads, contacts, broadcasts in the background, scheduled sends and every other call need a connected number: they answer 403 not_in_instant_sandbox here."
  },
  "next": "For a real WhatsApp number call create_account with the person's e-mail address: they confirm, connect their number and choose a plan.",
  "documentation_url": "https://www.app2email.com/docs/api/sandbox"
}
```

## Errors

[`internal_error`](https://www.app2email.com/docs/api/errors#internal_error), [`rate_limited`](https://www.app2email.com/docs/api/errors#rate_limited), [`route_not_found`](https://www.app2email.com/docs/api/errors#route_not_found), [`sandbox_unavailable`](https://www.app2email.com/docs/api/errors#sandbox_unavailable)

## Example

```bash
curl -X POST "https://api.app2email.com/v1/account/sandbox" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## OpenAPI

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "app2email WhatsApp API",
    "version": "1.4.0"
  },
  "servers": [
    {
      "url": "https://api.app2email.com"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/v1/account/sandbox": {
      "post": {
        "tags": [
          "Account management"
        ],
        "operationId": "createSandbox",
        "summary": "Instant sandbox: try the API with no account",
        "description": "No key, no body, no person. Answers an instant sandbox key (a2es_..., valid 7 days) for app2email's demo number +12025550100, where pretend customers answer and nothing reaches WhatsApp. Send the key as Authorization: Bearer on `base_url` (GET /me, GET /templates, POST /messages, GET /messages, GET /conversations, PUT /conversations/{contact}/owner, GET /events, and POST /sandbox/inbound to make a pretend customer write) or on the MCP server. Requests, answers, errors and events have the shapes of the real API, and templates are checked by the same code. Each key has its own state, kept in memory for 24 hours after the last call. Any other call there answers 403 not_in_instant_sandbox. Limit: 10 keys an hour per address.",
        "security": [],
        "parameters": [],
        "responses": {
          "200": {
            "description": "The key (shown once), the demo number, the pretend customers and the first calls to make.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstantSandboxResponse"
                },
                "example": {
                  "success": true,
                  "request_id": "s4ndb",
                  "instant_sandbox": {
                    "api_key": "a2es_000qlA9iTHS1NETB9JExampleExampleExampleExampleExampleExampleExampleExampleExampleExampleExample0",
                    "expires": "2026-11-22T03:00:00.000Z",
                    "number": "12025550100",
                    "base_url": "https://api.app2email.com/v1/12025550100",
                    "mcp_url": "https://api.app2email.com/mcp",
                    "authorization": "Authorization: Bearer <api_key>",
                    "what_it_is": "A demo WhatsApp number with pretend customers. Requests and answers have the shapes of the real API; nothing reaches WhatsApp, and nobody else sees this key's messages. Its state lives in memory for 24 hours after the last call.",
                    "test_contacts": [
                      {
                        "number": "12025550101",
                        "name": "Ava",
                        "behaviour": "answers every message a few seconds later"
                      },
                      {
                        "number": "12025550102",
                        "name": "Ben",
                        "behaviour": "reads, never answers: a free-form message to him is 422 outside_24h_window"
                      },
                      {
                        "number": "12025550103",
                        "name": "Cara",
                        "behaviour": "delivery fails: message.status failed and message.failed"
                      },
                      {
                        "number": "12025550104",
                        "name": "Dan",
                        "behaviour": "answers STOP: contact.opted_out, then a marketing template to him is 403 recipient_opted_out"
                      },
                      {
                        "number": "12025550105",
                        "name": "Eve",
                        "behaviour": "asks for a person: set the conversation's owner to human"
                      }
                    ],
                    "templates": [
                      "hello_world (en_US, UTILITY)",
                      "order_update (en, UTILITY)",
                      "weekend_offer (en, MARKETING)"
                    ],
                    "calls": [
                      "GET /me",
                      "GET /templates",
                      "POST /messages",
                      "GET /messages",
                      "GET /conversations",
                      "GET /conversations/{contact}",
                      "PUT /conversations/{contact}/owner",
                      "GET /events",
                      "POST /sandbox/inbound"
                    ],
                    "try_first": [
                      {
                        "step": 1,
                        "call": "GET https://api.app2email.com/v1/12025550100/templates",
                        "why": "each template comes with a complete example_request"
                      },
                      {
                        "step": 2,
                        "call": "POST https://api.app2email.com/v1/12025550100/messages",
                        "body": {
                          "to": "12025550101",
                          "type": "template",
                          "template": {
                            "name": "order_update",
                            "language": {
                              "code": "en"
                            },
                            "components": [
                              {
                                "type": "body",
                                "parameters": [
                                  {
                                    "type": "text",
                                    "text": "Ava"
                                  },
                                  {
                                    "type": "text",
                                    "text": "#1234"
                                  }
                                ]
                              }
                            ]
                          }
                        },
                        "why": "Ava answers a few seconds later"
                      },
                      {
                        "step": 3,
                        "call": "GET https://api.app2email.com/v1/12025550100/events?wait=25",
                        "why": "message.status sent, delivered, read, then message.received with Ava's answer. Pass the answer's cursor as ?after= on the next call"
                      },
                      {
                        "step": 4,
                        "call": "POST https://api.app2email.com/v1/12025550100/messages",
                        "body": {
                          "to": "12025550101",
                          "type": "text",
                          "text": {
                            "body": "It arrives on Friday."
                          }
                        },
                        "why": "a free-form reply: allowed because Ava wrote in the last 24 hours"
                      }
                    ],
                    "not_here": "Webhooks (use GET /events), media uploads, contacts, broadcasts in the background, scheduled sends and every other call need a connected number: they answer 403 not_in_instant_sandbox here."
                  },
                  "next": "For a real WhatsApp number call create_account with the person's e-mail address: they confirm, connect their number and choose a plan.",
                  "documentation_url": "https://www.app2email.com/docs/api/sandbox"
                }
              }
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-a2e-scope": "",
        "x-a2e-sandbox": "live",
        "x-a2e-error-codes": [
          "internal_error",
          "rate_limited",
          "route_not_found",
          "sandbox_unavailable"
        ],
        "x-a2e-mcp-tool": "create_sandbox",
        "x-a2e-webhook-events": [],
        "x-a2e-needs": null
      }
    }
  },
  "components": {
    "schemas": {
      "AudioContent": {
        "type": "object",
        "description": "aac, amr, mp3, m4a or ogg (OPUS), up to 16 MB. No caption.",
        "properties": {
          "link": {
            "type": "string",
            "format": "uri",
            "description": "Public http(s) URL. app2email downloads the file and uploads it to WhatsApp."
          },
          "data": {
            "type": "string",
            "format": "byte",
            "description": "The file, base64 encoded."
          },
          "id": {
            "type": "string",
            "description": "A media id from POST /media."
          },
          "filename": {
            "type": "string"
          },
          "mime_type": {
            "type": "string"
          },
          "voice": {
            "type": "boolean",
            "description": "true: a voice message (play button, transcript). Ogg with the OPUS codec only; app2email does not convert."
          }
        }
      },
      "Component": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "header",
              "body",
              "button",
              "carousel",
              "limited_time_offer"
            ]
          },
          "sub_type": {
            "type": "string",
            "enum": [
              "url",
              "quick_reply",
              "copy_code",
              "flow",
              "catalog",
              "mpm",
              "spm",
              "order_details"
            ],
            "description": "Buttons only."
          },
          "index": {
            "type": "string",
            "example": "0",
            "description": "Buttons only: position of the button in the template, starting at 0."
          },
          "parameters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Parameter"
            }
          },
          "cards": {
            "type": "array",
            "description": "type 'carousel': one entry per card of the approved template, {card_index, components: [header, body, button...]}.",
            "items": {
              "type": "object",
              "properties": {
                "card_index": {
                  "type": "integer"
                },
                "components": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Component"
                  }
                }
              }
            }
          }
        }
      },
      "ContactCard": {
        "type": "object",
        "required": [
          "name"
        ],
        "description": "One vCard, as WhatsApp Cloud API.",
        "properties": {
          "name": {
            "type": "object",
            "required": [
              "formatted_name"
            ],
            "properties": {
              "formatted_name": {
                "type": "string",
                "example": "Jane Citizen"
              },
              "first_name": {
                "type": "string"
              },
              "last_name": {
                "type": "string"
              },
              "middle_name": {
                "type": "string"
              },
              "prefix": {
                "type": "string"
              },
              "suffix": {
                "type": "string"
              }
            }
          },
          "phones": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "phone": {
                  "type": "string"
                },
                "type": {
                  "type": "string",
                  "example": "CELL"
                },
                "wa_id": {
                  "type": "string"
                }
              }
            }
          },
          "emails": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "email": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              }
            }
          },
          "addresses": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "org": {
            "type": "object",
            "properties": {
              "company": {
                "type": "string"
              },
              "department": {
                "type": "string"
              },
              "title": {
                "type": "string"
              }
            }
          },
          "urls": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              }
            }
          },
          "birthday": {
            "type": "string",
            "example": "1990-01-31"
          }
        }
      },
      "Currency": {
        "type": "object",
        "properties": {
          "fallback_value": {
            "type": "string",
            "example": "$10.50"
          },
          "code": {
            "type": "string",
            "example": "USD"
          },
          "amount_1000": {
            "type": "integer",
            "example": 10500
          }
        }
      },
      "DateTime": {
        "type": "object",
        "properties": {
          "fallback_value": {
            "type": "string",
            "example": "February 25, 2026"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message",
          "how_to_fix"
        ],
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "account_deactivated",
              "account_not_confirmed",
              "account_service_error",
              "account_service_unavailable",
              "api_key_expired",
              "api_key_number_mismatch",
              "api_key_old_format",
              "api_key_revoked",
              "approval_already_resolved",
              "approval_body_too_large",
              "approval_expired",
              "approval_not_found",
              "automation_not_found",
              "background_start_failed",
              "block_list_busy",
              "block_list_full",
              "block_not_found",
              "block_users_error",
              "block_users_failed",
              "booking_cancelled",
              "booking_not_enabled",
              "booking_not_found",
              "booking_slot_taken",
              "broadcast_cancelled",
              "broadcast_not_cancellable",
              "broadcast_not_found",
              "bsuid_not_supported",
              "call_permission_required",
              "caption_not_supported",
              "caption_too_long",
              "catcher_not_found",
              "client_exists",
              "client_not_editable",
              "client_not_found",
              "connection_failed",
              "connection_in_use",
              "connection_not_found",
              "contact_book_error",
              "contact_not_found",
              "conversation_not_found",
              "daily_cap_reached",
              "dataset_not_found",
              "delivery_in_progress",
              "delivery_not_found",
              "display_name_not_approved",
              "duplicate_recipients",
              "email_not_sent",
              "encryption_key_managed",
              "flow_blocked_by_integrity",
              "flow_cannot_publish",
              "flow_json_download_failed",
              "flow_json_not_found",
              "flow_json_too_large",
              "flow_name_taken",
              "flow_not_deletable",
              "flow_not_editable",
              "flow_not_found",
              "flow_not_published",
              "flow_rejected",
              "form_exists",
              "form_has_submissions",
              "form_not_found",
              "form_not_published",
              "free_form_single_recipient",
              "hold_expired",
              "hold_not_found",
              "idempotency_key_reused",
              "idempotency_request_in_progress",
              "idempotency_request_interrupted",
              "insufficient_scope",
              "internal_error",
              "invalid_addons",
              "invalid_analytics_query",
              "invalid_answers",
              "invalid_api_key",
              "invalid_auth_template",
              "invalid_authorization_header",
              "invalid_automation",
              "invalid_base64",
              "invalid_block",
              "invalid_booking",
              "invalid_bsuid",
              "invalid_call_request",
              "invalid_call_settings",
              "invalid_callback_data",
              "invalid_catalog_id",
              "invalid_client_request",
              "invalid_compare_days",
              "invalid_compliance_info",
              "invalid_components",
              "invalid_connection",
              "invalid_contact_email",
              "invalid_contacts",
              "invalid_contacts_message",
              "invalid_conversation_starters",
              "invalid_conversion_events",
              "invalid_coupon",
              "invalid_csv",
              "invalid_cursor",
              "invalid_direction",
              "invalid_display_name",
              "invalid_email",
              "invalid_estimate",
              "invalid_event_type",
              "invalid_events",
              "invalid_flow_categories",
              "invalid_flow_field",
              "invalid_flow_id",
              "invalid_flow_json",
              "invalid_flow_name",
              "invalid_form",
              "invalid_guests",
              "invalid_idempotency_key",
              "invalid_identity_key_hash",
              "invalid_insights_request",
              "invalid_interactive",
              "invalid_json",
              "invalid_keep_old_for_hours",
              "invalid_key_request",
              "invalid_library_filter",
              "invalid_limit",
              "invalid_link",
              "invalid_list",
              "invalid_location",
              "invalid_marketing_api",
              "invalid_media_id",
              "invalid_media_link",
              "invalid_media_type",
              "invalid_member",
              "invalid_months",
              "invalid_note",
              "invalid_number",
              "invalid_number_in_url",
              "invalid_numbers",
              "invalid_oba_request",
              "invalid_onboarding_request",
              "invalid_optimization_spec",
              "invalid_owner",
              "invalid_partner_settings",
              "invalid_payment",
              "invalid_phone",
              "invalid_plan",
              "invalid_poll",
              "invalid_profile",
              "invalid_public_key",
              "invalid_qr_code",
              "invalid_range",
              "invalid_reaction",
              "invalid_recipients",
              "invalid_redirect_url",
              "invalid_reply_to",
              "invalid_segment",
              "invalid_send_at",
              "invalid_series",
              "invalid_service",
              "invalid_setting",
              "invalid_settings",
              "invalid_setup",
              "invalid_slug",
              "invalid_start",
              "invalid_status",
              "invalid_submission",
              "invalid_template_category",
              "invalid_template_components",
              "invalid_template_field",
              "invalid_template_ids",
              "invalid_template_language",
              "invalid_template_name",
              "invalid_template_preview",
              "invalid_test_event",
              "invalid_text",
              "invalid_ticket_check_in",
              "invalid_ticket_code",
              "invalid_ticket_event",
              "invalid_ticket_order",
              "invalid_time",
              "invalid_to",
              "invalid_username",
              "invalid_users",
              "invalid_wait",
              "invalid_webhook_format",
              "invalid_webhook_headers",
              "invalid_webhook_secret",
              "invalid_webhook_url",
              "ip_not_allowed",
              "key_limit_reached",
              "key_limits_unavailable",
              "key_not_found",
              "link_not_found",
              "link_not_usable",
              "list_not_found",
              "marketing_disabled_on_cloud_api",
              "marketing_per_user_limit",
              "marketing_status_lookup_failed",
              "media_delete_failed",
              "media_download_error",
              "media_download_failed",
              "media_lookup_failed",
              "media_lookups_paused",
              "media_not_found",
              "media_too_large",
              "media_type_not_allowed",
              "media_upload_error",
              "media_upload_failed",
              "member_not_found",
              "message_not_found",
              "message_too_old",
              "messaging_limit_restricted",
              "missing_api_key",
              "missing_file",
              "missing_interactive",
              "missing_media",
              "missing_message_id",
              "missing_numbers",
              "missing_template_language",
              "missing_template_name",
              "missing_text",
              "missing_url",
              "monthly_cap_reached",
              "monthly_limit_reached",
              "not_in_instant_sandbox",
              "note_not_found",
              "nothing_to_change",
              "number_already_verified",
              "number_not_found",
              "number_not_live",
              "optin_not_found",
              "outside_24h_window",
              "package_not_found",
              "parameter_value_invalid",
              "partner_closed",
              "partner_service_unavailable",
              "partner_suspended",
              "payment_link_failed",
              "payment_not_found",
              "payment_provider_error",
              "payments_not_connected",
              "plan_already_active",
              "plan_not_allowed",
              "plan_not_available",
              "poll_not_found",
              "profile_photo_failed",
              "qr_code_not_found",
              "range_too_large",
              "rate_limited",
              "reaction_too_old",
              "recipient_identity_changed",
              "recipient_in_experiment",
              "recipient_is_sender",
              "recipient_not_allowed",
              "recipient_not_opted_in",
              "recipient_opted_out",
              "recipient_stopped_marketing",
              "recipient_unreachable",
              "refund_not_possible",
              "register_limit_reached",
              "request_log_unavailable",
              "request_not_found",
              "request_too_large",
              "required_parameter_missing",
              "route_not_found",
              "sandbox_key",
              "sandbox_recipient",
              "sandbox_unavailable",
              "schedule_failed",
              "segment_and_recipients",
              "segment_empty",
              "segment_exists",
              "segment_not_found",
              "send_at_in_past",
              "send_at_too_far",
              "service_not_live",
              "shop_changed",
              "shop_failed",
              "shop_invalid",
              "shop_limit",
              "shop_not_enabled",
              "shop_not_found",
              "shop_not_ready",
              "shop_not_tracked",
              "shop_order_problems",
              "shop_payment_failed",
              "shop_sku_taken",
              "slug_taken",
              "stage_not_allowed",
              "submission_not_found",
              "submit_not_enabled",
              "submit_not_ready",
              "template_already_exists",
              "template_archive_failed",
              "template_category_locked",
              "template_compare_unavailable",
              "template_delete_failed",
              "template_disabled",
              "template_format_policy",
              "template_insights_confirm_required",
              "template_insights_not_enabled",
              "template_insights_unavailable",
              "template_language_not_found",
              "template_language_required",
              "template_limit_reached",
              "template_lookup_failed",
              "template_name_reserved",
              "template_not_approved",
              "template_not_editable",
              "template_not_found",
              "template_not_marketing",
              "template_parameter_count_mismatch",
              "template_parameter_format_mismatch",
              "template_parameter_invalid",
              "template_parameters_invalid",
              "template_paused",
              "template_rejected",
              "template_sample_media_failed",
              "template_text_too_long",
              "template_unarchive_failed",
              "test_event_too_large",
              "text_too_long",
              "ticket_check_in_not_found",
              "ticket_code_not_found",
              "ticket_date_not_found",
              "ticket_event_not_found",
              "ticket_event_not_publishable",
              "ticket_limit_reached",
              "ticket_not_allowed",
              "ticket_not_found",
              "ticket_order_not_found",
              "ticket_seat_not_available",
              "ticket_type_not_found",
              "tickets_not_enabled",
              "tickets_not_on_sale",
              "tickets_sold_out",
              "to_and_recipients",
              "too_late",
              "too_many_catchers",
              "too_many_invites",
              "too_many_messages_to_recipient",
              "too_many_numbers",
              "too_many_recipients",
              "too_many_segments",
              "too_many_signups",
              "too_many_templates",
              "too_many_tests",
              "too_many_webhooks",
              "unsupported_content_type",
              "unsupported_message_type",
              "username_account_not_linked",
              "username_change_limit",
              "username_not_available",
              "username_not_eligible",
              "username_taken",
              "voice_needs_ogg_opus",
              "waitlist_not_found",
              "waitlist_not_offered",
              "waitlist_not_set_up",
              "webhook_not_found",
              "webhook_url_in_use",
              "whatsapp_account_locked",
              "whatsapp_account_restricted",
              "whatsapp_connection_problem",
              "whatsapp_error",
              "whatsapp_flow_failed",
              "whatsapp_maintenance",
              "whatsapp_number_not_registered",
              "whatsapp_parameter_error",
              "whatsapp_payment_issue",
              "whatsapp_permission_missing",
              "whatsapp_rate_limit",
              "whatsapp_unavailable"
            ],
            "description": "Stable error code, safe to use in your own logic."
          },
          "message": {
            "type": "string",
            "description": "What is wrong, in plain words."
          },
          "how_to_fix": {
            "type": "string",
            "description": "What to change to make the request work."
          },
          "documentation_url": {
            "type": "string",
            "example": "https://www.app2email.com/docs/api/errors#template_not_found",
            "description": "Where this error is explained."
          },
          "is_retriable": {
            "type": "boolean",
            "description": "true: the same request can work later without a change (limits, caps, trouble on our side or WhatsApp's, a request with the same Idempotency-Key still running)."
          },
          "retry_after_seconds": {
            "type": "integer",
            "description": "How long to wait before trying again, when known (also the Retry-After header)."
          },
          "details": {
            "type": "object",
            "additionalProperties": true,
            "description": "Extra information, eg the problems found, available templates or languages."
          },
          "example_request": {
            "$ref": "#/components/schemas/SendTemplateRequest"
          },
          "whatsapp_error": {
            "$ref": "#/components/schemas/WhatsAppError"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "request_id": {
            "type": "string",
            "example": "kxrkf",
            "description": "Quote this when contacting support."
          },
          "error": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "FreeFormMedia": {
        "type": "object",
        "description": "Give exactly one of: link, data or id. 'filename' is shown to the recipient for documents.",
        "properties": {
          "link": {
            "type": "string",
            "format": "uri",
            "example": "https://example.com/photo.jpg",
            "description": "Public http(s) URL. app2email downloads the file and uploads it to WhatsApp."
          },
          "data": {
            "type": "string",
            "format": "byte",
            "description": "The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted."
          },
          "id": {
            "type": "string",
            "description": "A media id from POST /media (or uploaded to WhatsApp for this number)."
          },
          "filename": {
            "type": "string",
            "example": "invoice.pdf",
            "description": "Needed with 'data' for documents."
          },
          "mime_type": {
            "type": "string",
            "example": "application/pdf",
            "description": "Optional. The type is detected from the file where possible."
          },
          "caption": {
            "type": "string",
            "maxLength": 1024,
            "example": "Your parcel",
            "description": "Optional text under the image, video or document."
          }
        }
      },
      "FreeFormText": {
        "type": "object",
        "required": [
          "body"
        ],
        "properties": {
          "body": {
            "type": "string",
            "example": "Thanks, it arrives on Friday.",
            "description": "The text. Up to 4096 characters."
          },
          "preview_url": {
            "type": "boolean",
            "default": false,
            "description": "true: show a preview of a link in the text."
          }
        }
      },
      "InstantSandbox": {
        "type": "object",
        "description": "A key that works at once on app2email's demo number, where pretend customers answer and nothing reaches WhatsApp. Left out of create_account's answer when it could not be made.",
        "properties": {
          "api_key": {
            "type": "string",
            "description": "The instant sandbox key (a2es_..., 96 characters). Shown once. Send it as Authorization: Bearer on base_url or mcp_url. It works only on the demo number."
          },
          "expires": {
            "type": "string",
            "format": "date-time",
            "description": "7 days after it was made."
          },
          "number": {
            "type": "string",
            "example": "12025550100",
            "description": "The demo number: the {number} of every call."
          },
          "base_url": {
            "type": "string",
            "format": "uri",
            "example": "https://api.app2email.com/v1/12025550100"
          },
          "mcp_url": {
            "type": "string",
            "format": "uri",
            "example": "https://api.app2email.com/mcp"
          },
          "authorization": {
            "type": "string"
          },
          "what_it_is": {
            "type": "string"
          },
          "test_contacts": {
            "type": "array",
            "description": "The pretend customers: the only numbers the sandbox writes to.",
            "items": {
              "type": "object",
              "properties": {
                "number": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "behaviour": {
                  "type": "string"
                }
              }
            }
          },
          "templates": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "calls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The calls the demo number has. Any other: 403 not_in_instant_sandbox."
          },
          "try_first": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "step": {
                  "type": "integer"
                },
                "call": {
                  "type": "string"
                },
                "body": {
                  "type": "object"
                },
                "why": {
                  "type": "string"
                }
              }
            }
          },
          "not_here": {
            "type": "string"
          }
        }
      },
      "InstantSandboxResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "request_id": {
            "type": "string"
          },
          "instant_sandbox": {
            "$ref": "#/components/schemas/InstantSandbox"
          },
          "next": {
            "type": "string"
          },
          "documentation_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Interactive": {
        "type": "object",
        "required": [
          "type",
          "action"
        ],
        "description": "WhatsApp's interactive object. type button: action.buttons, up to 3 reply buttons (title up to 20 characters; the shortcut \"buttons\": [\"Confirm\", \"Change\"] works too). type list: action.button (the text that opens the list) and action.sections with rows (up to 10 rows in all; a row can be a plain title). type cta_url: action.parameters {display_text, url}. header: text (60 characters), or image / video / document (link, data or id) for button and cta_url. body.text up to 1024 characters, footer.text up to 60. Also (WhatsApp Cloud API's objects): carousel (action.cards: 2 to 10, image or video header, one URL button or quick replies each; or product cards {card_index, type: 'product', action: {product_retailer_id, catalog_id}}), location_request_message, request_contact_info, flow (action.parameters: flow_message_version '3', flow_id or flow_name, flow_cta), product and product_list (a connected catalog), catalog_message, call_permission_request and voice_call (Calling), address_message (India; optional text header), order_details and order_status (payments). The fixed action.name of a kind is filled in when left out.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "button",
              "list",
              "cta_url",
              "carousel",
              "location_request_message",
              "request_contact_info",
              "flow",
              "product",
              "product_list",
              "catalog_message",
              "call_permission_request",
              "voice_call",
              "address_message",
              "order_details",
              "order_status"
            ]
          },
          "header": {
            "type": "object",
            "additionalProperties": true,
            "example": {
              "type": "text",
              "text": "Booking"
            }
          },
          "body": {
            "type": "object",
            "required": [
              "text"
            ],
            "properties": {
              "text": {
                "type": "string",
                "maxLength": 1024,
                "example": "Confirm your booking for Friday 10:00?"
              }
            }
          },
          "footer": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string",
                "maxLength": 60
              }
            }
          },
          "action": {
            "type": "object",
            "additionalProperties": true,
            "example": {
              "buttons": [
                {
                  "type": "reply",
                  "reply": {
                    "id": "yes",
                    "title": "Confirm"
                  }
                },
                {
                  "type": "reply",
                  "reply": {
                    "id": "no",
                    "title": "Change"
                  }
                }
              ]
            }
          }
        }
      },
      "Language": {
        "type": "object",
        "required": [
          "code"
        ],
        "description": "Required when the template exists in more than one language.",
        "properties": {
          "code": {
            "type": "string",
            "example": "en",
            "description": "Template language code, eg 'en', 'en_US', 'nl'."
          }
        }
      },
      "Location": {
        "type": "object",
        "required": [
          "latitude",
          "longitude"
        ],
        "properties": {
          "latitude": {
            "type": "string",
            "example": "-33.8688"
          },
          "longitude": {
            "type": "string",
            "example": "151.2093"
          },
          "name": {
            "type": "string"
          },
          "address": {
            "type": "string"
          }
        }
      },
      "LocationContent": {
        "type": "object",
        "required": [
          "latitude",
          "longitude"
        ],
        "properties": {
          "latitude": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "example": -33.8568
          },
          "longitude": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "example": 151.2153
          },
          "name": {
            "type": "string",
            "example": "Sydney Opera House"
          },
          "address": {
            "type": "string",
            "example": "Bennelong Point, Sydney NSW 2000"
          }
        }
      },
      "Media": {
        "type": "object",
        "description": "Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out.",
        "properties": {
          "link": {
            "type": "string",
            "format": "uri",
            "example": "https://example.com/photo.jpg",
            "description": "Public http(s) URL. app2email downloads the file (no login, no private network addresses) and uploads it to WhatsApp."
          },
          "data": {
            "type": "string",
            "format": "byte",
            "description": "The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted."
          },
          "id": {
            "type": "string",
            "description": "A media id already uploaded to WhatsApp for this number."
          },
          "filename": {
            "type": "string",
            "example": "invoice.pdf",
            "description": "Shown to the recipient for documents. Also helps detect the file type."
          },
          "mime_type": {
            "type": "string",
            "example": "application/pdf",
            "description": "Optional. The type is detected from the file where possible."
          }
        }
      },
      "Parameter": {
        "type": "object",
        "required": [
          "type"
        ],
        "description": "One value. Set 'type' and the matching field, eg {\"type\":\"text\",\"text\":\"John\"} or {\"type\":\"image\",\"image\":{\"link\":\"https://...\"}}.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "text",
              "image",
              "video",
              "document",
              "location",
              "currency",
              "date_time",
              "payload",
              "coupon_code",
              "action",
              "product",
              "limited_time_offer"
            ]
          },
          "parameter_name": {
            "type": "string",
            "description": "For templates with NAMED placeholders, eg 'first_name' for {{first_name}}."
          },
          "text": {
            "type": "string",
            "description": "type 'text'. No new lines, tabs or more than 4 spaces in a row."
          },
          "image": {
            "$ref": "#/components/schemas/Media"
          },
          "video": {
            "$ref": "#/components/schemas/Media"
          },
          "document": {
            "$ref": "#/components/schemas/Media"
          },
          "location": {
            "$ref": "#/components/schemas/Location"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "date_time": {
            "$ref": "#/components/schemas/DateTime"
          },
          "payload": {
            "type": "string",
            "description": "type 'payload': quick reply button payload."
          },
          "coupon_code": {
            "type": "string",
            "description": "type 'coupon_code': copy code button value."
          },
          "action": {
            "type": "object",
            "additionalProperties": true,
            "description": "type 'action': flow / catalog button data, as WhatsApp Cloud API."
          },
          "product": {
            "type": "object",
            "properties": {
              "product_retailer_id": {
                "type": "string"
              },
              "catalog_id": {
                "type": "string"
              }
            },
            "description": "type 'product': a product header."
          },
          "limited_time_offer": {
            "type": "object",
            "properties": {
              "expiration_time_ms": {
                "type": "integer",
                "example": 1767225600000
              }
            },
            "description": "type 'limited_time_offer': when the offer ends (ms since 1970)."
          }
        }
      },
      "ReactionContent": {
        "type": "object",
        "required": [
          "message_id",
          "emoji"
        ],
        "properties": {
          "message_id": {
            "type": "string",
            "example": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBQzQUZCMTY0MDc2MUYwNzBDNTY5MAA=",
            "description": "A message the contact sent, up to 30 days old."
          },
          "emoji": {
            "type": "string",
            "example": "👍",
            "description": "One emoji. \"\" removes your reaction."
          }
        }
      },
      "Recipient": {
        "type": "object",
        "required": [
          "to"
        ],
        "properties": {
          "to": {
            "type": "string",
            "example": "61412345678",
            "description": "One number, with country code."
          },
          "components": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Component"
            },
            "description": "Only what differs for this number, eg its body values. The rest comes from template.components."
          },
          "recipient_identity_key_hash": {
            "type": "string",
            "maxLength": 200,
            "description": "Optional: this contact's identity_key_hash (see the request's)."
          }
        }
      },
      "SendTemplateRequest": {
        "type": "object",
        "description": "A WhatsApp message in the format of WhatsApp Cloud API (Meta's exact body works unchanged): a template (type 'template', the default, any time), or within 24 hours of the contact's last message a free-form text, image, video, document, audio, sticker, location, contacts, reaction or interactive message. Meta's mark-read body {messaging_product, status: 'read', message_id, typing_indicator?} marks a message as read. Give 'to' or 'recipients' (templates only).",
        "properties": {
          "messaging_product": {
            "type": "string",
            "enum": [
              "whatsapp"
            ],
            "description": "Optional. Always 'whatsapp'."
          },
          "recipient_type": {
            "type": "string",
            "enum": [
              "individual"
            ],
            "description": "Optional. Always 'individual'."
          },
          "to": {
            "type": "string",
            "example": "61412345678",
            "description": "Recipient's WhatsApp number with country code. Digits only is best (spaces, '+', '-' are removed). Several recipients: separate the numbers with commas, eg \"61412345678,61498765432\" (semicolons and new lines work too), or send a JSON array of numbers. Each number gets its own message, and the response lists the result per number in 'results'. A free-form message (not 'template') goes to one number. A business-scoped user id (eg 61.AbC123, from from_user_id) is accepted as it is."
          },
          "recipient": {
            "type": "string",
            "example": "61.AbC123xyz",
            "description": "Optional, instead of 'to': one contact, a phone number or a business-scoped user id (BSUID). Sent to WhatsApp as 'recipient'."
          },
          "segment": {
            "type": "string",
            "example": "VIP, consented",
            "description": "Optional, app2email only, instead of 'to' / 'recipients': the id or name of a saved segment (GET /segments). Templates only. Each contact's named template parameters without a value are filled from its custom_fields ('name' from the contact's name). Recorded as a broadcast."
          },
          "type": {
            "type": "string",
            "enum": [
              "template",
              "text",
              "image",
              "video",
              "document",
              "interactive",
              "audio",
              "sticker",
              "location",
              "contacts",
              "reaction"
            ],
            "default": "template",
            "description": "'template' (default): an approved template. Otherwise a free-form message within the 24 hour window; the field of the same name holds it. Left out with status 'read': mark as read."
          },
          "interactive": {
            "$ref": "#/components/schemas/Interactive",
            "description": "type 'interactive': reply buttons, a list, or a URL button."
          },
          "template": {
            "$ref": "#/components/schemas/Template"
          },
          "text": {
            "$ref": "#/components/schemas/FreeFormText",
            "description": "type 'text': the message."
          },
          "image": {
            "$ref": "#/components/schemas/FreeFormMedia",
            "description": "type 'image': link, data+filename or id, and an optional caption."
          },
          "video": {
            "$ref": "#/components/schemas/FreeFormMedia",
            "description": "type 'video': link, data+filename or id, and an optional caption."
          },
          "document": {
            "$ref": "#/components/schemas/FreeFormMedia",
            "description": "type 'document': link, data+filename or id, and an optional caption."
          },
          "reply_to": {
            "type": "string",
            "example": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
            "description": "Optional, free-form only: the message_id of one of the contact's messages, quoted by this one. Meta's 'context': {\"message_id\": ...} works too."
          },
          "send_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-02T09:00:00+11:00",
            "description": "Optional, templates only: send later. ISO 8601 with a time zone ('Z' or '+11:00'), 1 minute to 29 days ahead. The answer is HTTP 202 with status 'scheduled'."
          },
          "campaign_name": {
            "type": "string",
            "maxLength": 100,
            "example": "October newsletter",
            "description": "Optional, app2email only. Several numbers in 'to' (or 'recipients'): the name of the broadcast this list is recorded as (Activity Log under Broadcasts). Default \"API: <template name>\". Not used for one number."
          },
          "recipients": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Recipient"
            },
            "description": "Optional, app2email only, instead of 'to': each number with its own values. Each entry's components replace the shared template.components of the same type (a button: the same index). Every number is checked before anything is sent."
          },
          "dry_run": {
            "type": "boolean",
            "default": false,
            "description": "Optional, app2email only. true: check everything and answer with the exact WhatsApp message per number, without sending, logging or counting anything."
          },
          "background": {
            "type": "boolean",
            "default": false,
            "description": "Optional, app2email only. true: answer HTTP 202 once everything is checked and the media uploaded, then send. Progress: broadcast.status_url (GET /v1/{number}/broadcasts/{code}) or the broadcast.completed webhook event."
          },
          "audio": {
            "$ref": "#/components/schemas/AudioContent",
            "description": "type 'audio'."
          },
          "sticker": {
            "$ref": "#/components/schemas/StickerContent",
            "description": "type 'sticker'."
          },
          "location": {
            "$ref": "#/components/schemas/LocationContent",
            "description": "type 'location'."
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactCard"
            },
            "description": "type 'contacts': 1 to 20 cards."
          },
          "reaction": {
            "$ref": "#/components/schemas/ReactionContent",
            "description": "type 'reaction'."
          },
          "context": {
            "type": "object",
            "properties": {
              "message_id": {
                "type": "string"
              }
            },
            "description": "Meta's form of reply_to."
          },
          "callback_data": {
            "type": "string",
            "maxLength": 512,
            "example": "order-1234",
            "description": "Optional. Sent to WhatsApp as biz_opaque_callback_data; back as data.callback_data in this message's message.status events. Meta's own field name works too."
          },
          "recipient_identity_key_hash": {
            "type": "string",
            "maxLength": 200,
            "example": "DF2lS5v2W6x=",
            "description": "Optional, one recipient (per number: in recipients[]): delivered only while the contact's identity key has this hash (message.received data.identity_key_hash); else message.failed, 137000 recipient_identity_changed. Needs PUT /settings/identity-check."
          },
          "marketing_api": {
            "type": "string",
            "enum": [
              "auto",
              "cloud_api",
              "mm_api"
            ],
            "description": "Optional, MARKETING templates: the path for this send (true = mm_api, false = cloud_api). Default: the number's setting messages.marketing_route (auto)."
          },
          "product_policy": {
            "type": "string",
            "enum": [
              "CLOUD_API_FALLBACK",
              "STRICT"
            ],
            "description": "Optional, Marketing Messages API only: STRICT = no fallback to the Cloud API. Default CLOUD_API_FALLBACK."
          },
          "message_activity_sharing": {
            "type": "boolean",
            "description": "Optional, Marketing Messages API only: share read and click activity with Meta for this message."
          },
          "status": {
            "type": "string",
            "enum": [
              "read"
            ],
            "description": "Meta's mark-read body: 'read' with message_id (no type)."
          },
          "message_id": {
            "type": "string",
            "description": "Meta's mark-read body: the received message."
          },
          "typing_indicator": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "text"
                ]
              }
            },
            "description": "Meta's mark-read body: also show the typing indicator."
          }
        }
      },
      "StickerContent": {
        "type": "object",
        "description": "WebP only: up to 100 KB static, 500 KB animated. No caption.",
        "properties": {
          "link": {
            "type": "string",
            "format": "uri",
            "description": "Public http(s) URL. app2email downloads the file and uploads it to WhatsApp."
          },
          "data": {
            "type": "string",
            "format": "byte",
            "description": "The file, base64 encoded."
          },
          "id": {
            "type": "string",
            "description": "A media id from POST /media."
          },
          "filename": {
            "type": "string"
          },
          "mime_type": {
            "type": "string"
          }
        }
      },
      "Template": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "order_update",
            "description": "Exact name of an APPROVED template."
          },
          "language": {
            "$ref": "#/components/schemas/Language"
          },
          "components": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Component"
            },
            "description": "Values for the template's placeholders and media. Leave out for templates without parameters."
          }
        }
      },
      "WhatsAppError": {
        "type": "object",
        "description": "WhatsApp's (Meta's) own error, when the error came from WhatsApp.",
        "properties": {
          "code": {
            "type": "integer",
            "example": 132000
          },
          "message": {
            "type": "string"
          },
          "details": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "fbtrace_id": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization: Bearer <your API key>"
      }
    }
  }
}
```

