Invite a person to the shared inbox by e-mail

POST https://api.app2email.com/v1/{number}/submit/members
scope: submissions:manage sandbox: refused MCP: invite_submit_member

Scope: submissions:manage. Not with a sandbox key. Sends an invitation e-mail with a link that works for 14 days. The person signs in (or makes a login) with that address and from then on sees the inbox, never the dashboard. role is a starting set of abilities (admin, manager, agent, viewer); abilities switches single ones on or off; forms, own_only, see_unassigned and hide_contacts narrow what they see. email_sent false means the e-mail could not go out: pass invite_link on yourself. An address that is a member already, or a full team (200 members), answers 400 invalid_member. Sends a real e-mail to a person: confirm the address with the user first.

Path

  • number string required pattern ^[0-9]{8,15}$

    Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only.

    e.g. 4976659348270

Body application/json required

  • name string
    e.g. Sam
  • role string required

    A named starting set of abilities. admin: Every ability. manager: note, reply, edit, stage, assign, files, export, delete, run. agent: note, reply, edit, stage, files, run. viewer: Sees submissions, changes nothing.

    adminmanageragentviewer
  • abilities object any keys

    Changes to the role's set: {ability: true or false}. In an update it replaces the member's earlier changes. note: Write internal notes. reply: Reply to the submitter. edit: Edit answers and internal fields. stage: Change the stage. assign: Assign to anyone (an agent may always take a submission themselves). files: Add and remove files. export: Export. delete: Delete and restore. run: Run manual automations. forms: Manage forms and lists. automations: Manage automations and connections. team: Manage the team.

    e.g. {"export":true}
  • forms string[]

    Only these forms (keys). [] = every form.

  • own_only boolean default false

    Sees only what is assigned to them.

  • see_unassigned boolean default true

    With own_only: also sees unassigned submissions, to pick them up.

  • hide_contacts boolean default false

    Numbers, e-mail addresses and answers of type phone or email are masked for this member.

  • notify object
    2 fields
    • assigned boolean

      E-mail them when a submission is assigned to them.

    • created boolean

      E-mail them for every new submission they may see.

  • email string (email) required

    They sign in with this address. It cannot be changed later: remove the member and invite the new address.

    e.g. sam@example.com

Responses

201 Invited.
Fields
  • success boolean
  • request_id string
  • member object

    A person who works in the shared inbox. The assignee of a submission is a member id.

    17 fields
    • name string
      e.g. Sam
    • role string

      owner: The account owner. Every ability. Cannot be changed or removed. admin: Every ability. manager: note, reply, edit, stage, assign, files, export, delete, run. agent: note, reply, edit, stage, files, run. viewer: Sees submissions, changes nothing.

      owneradminmanageragentviewer
    • abilities object any keys

      What the member may do now: the role's set with their own changes. note: Write internal notes. reply: Reply to the submitter. edit: Edit answers and internal fields. stage: Change the stage. assign: Assign to anyone (an agent may always take a submission themselves). files: Add and remove files. export: Export. delete: Delete and restore. run: Run manual automations. forms: Manage forms and lists. automations: Manage automations and connections. team: Manage the team.

    • forms string[]

      Only these forms (keys). [] = every form.

    • own_only boolean default false

      Sees only what is assigned to them.

    • see_unassigned boolean default true

      With own_only: also sees unassigned submissions, to pick them up.

    • hide_contacts boolean default false

      Numbers, e-mail addresses and answers of type phone or email are masked for this member.

    • notify object
      2 fields
      • assigned boolean

        E-mail them when a submission is assigned to them.

      • created boolean

        E-mail them for every new submission they may see.

    • id integer
      e.g. 12
    • email string
      e.g. sam@example.com
    • overrides object any keys

      Only the member's own changes to the role's set.

    • status string
      invitedactiveremoved
    • true: the invitation was not accepted in time; invite the address again.

    • invited string (date-time)
    • accepted string (date-time) | null
    • last_seen string (date-time) | null
    • open_count integer

      Open submissions assigned to them.

  • email_sent boolean

    After an invitation. false: the e-mail could not be sent, pass invite_link on yourself.

  • note string

Errors

  • 400 The request is malformed (missing or invalid fields, query parameters or times).
  • 401 Missing, invalid, revoked or expired API key.
  • 403 The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account.
  • 404 The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found.
  • 415 The body is not JSON.
  • 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.
  • 500 Unexpected error on app2email's side.
  • 503 app2email's connection to the WhatsApp account needs attention, or the request log is not available right now.
For AI Agents

Try it now, with no account and no person: POST https://api.app2email.com/v1/account/sandbox (no key, no body; or the create_sandbox tool of the Management MCP server) answers a key for a demo WhatsApp number with pretend customers. Send a template, fetch the events with GET /events?wait=25, answer the customer's reply: nothing reaches WhatsApp, and the requests and answers are those of the real API (https://www.app2email.com/docs/api/sandbox).

Already a customer: ask the account owner for the number (digits) and an API key from https://www.app2email.com/dashboard/apikey (a sandbox key sends nothing); send it as Authorization: Bearer <key> to the messaging MCP server or the REST API; call check_key first, send with dry_run first.

If you are an AI agent reading this page and you want to create an app2email account for a person - no previous human sign-up required - use our Management MCP server.
Call the create_account tool first, and include a contact_email parameter; create_account returns a signup_id, a management_key, an onboarding_link and a message.
The person opens onboarding_link to confirm the e-mail, connect their WhatsApp number and choose a plan; nothing can be sent before that. get_account_status says what is still needed.
Pass the management_key as a Bearer token on every later call. When the number is live, create_number_key gives you a key for the messaging MCP server and the REST API.