# iSnap

> Developer documentation for the iSnap API: send and receive iMessage, RCS and SMS from real devices, manage lines, and receive events by webhook.

- [Introduction](https://docs.isnap.ai/introduction.md): The iSnap API sends and receives iMessage, RCS and SMS from real devices, manages the lines that carry them, and reports events by webhook.
- [Quickstart](https://docs.isnap.ai/quickstart.md): Takes you from an API key to a message you sent, read and followed by webhook, on a real line of your account.
- [Core concepts](https://docs.isnap.ai/concepts.md): Defines the terms the iSnap docs use: lines and their kinds, line and message statuses, accounts, services, chats, identifiers and timestamps.
- [Authentication](https://docs.isnap.ai/authentication.md): Describes the three kinds of iSnap key, where a line-scoped key applies, the order in which a request is checked, and every refusal.
- [AI agents](https://docs.isnap.ai/ai-agents.md): Gives the rules for an AI agent that calls the iSnap API, where every send reaches a real person even with a test key, and the checklist for a coding agent that writes a client.
- [Pagination](https://docs.isnap.ai/pagination.md): Gives the rules of each list operation of the iSnap API: cursors, page numbers, limits, order, filters and timestamps in queries.
- [Idempotency and retries](https://docs.isnap.ai/idempotency.md): Lists the operations of the iSnap API that read the Idempotency-Key header, what each does with a repeated request, and how to retry a write safely.
- [Errors and rate limits](https://docs.isnap.ai/errors-and-rate-limits.md): Describes the error format of the iSnap API, the errors every operation shares, what to retry, and the request-rate and message-operations limits with their headers.
- [Sending messages](https://docs.isnap.ai/guides/sending-messages.md): Send a message from a line, follow it to a final status, know when it goes out as SMS or RCS, and cancel it before it leaves.
- [Receiving messages](https://docs.isnap.ai/guides/receiving-messages.md): Receive the messages your lines get, read them and their chats, and know what iSnap records of messages typed on a line's device and how long it keeps them.
- [Attachments](https://docs.isnap.ai/guides/attachments.md): Upload a file, wait until it is ready, send it with a message, and read the files that your lines receive.
- [Chat features](https://docs.isnap.ai/guides/conversations.md): Add and remove reactions, show the typing indicator, send read receipts and contact cards, and receive the reactions of your contacts.
- [Recipient lookup](https://docs.isnap.ai/guides/lookup.md): Ask whether a phone number or an email address can receive iMessage, read the three kinds of answer, and stay within the lookup limits.
- [Sending limits](https://docs.isnap.ai/guides/sending-limits.md): Learn the five sending limits of a line, why and for how long iSnap holds a message, quiet hours, spacing, the reply lane and the order of messages to one recipient.
- [Getting a line](https://docs.isnap.ai/guides/getting-a-line.md): Compare the ways to get a line and who can use each, browse the marketplace, and reserve, activate, assign or create a line.
- [Pre-orders](https://docs.isnap.ai/guides/pre-orders.md): Order one rented iMessage line in the area codes you prefer, confirm the order, pay its first month as a direct account, and receive the line when iSnap hands it over.
- [BYOD lines](https://docs.isnap.ai/guides/byod.md): Create a BYOD line by pairing a Mac and iPhone, or an Android phone, that you or your user own, with an activation code.
- [Hosted macOS sessions](https://docs.isnap.ai/guides/hosted-macos-sessions.md): Rent a hosted macOS session as a wholesale partner, follow its anniversary, and cancel it or keep it through the API.
- [Managing lines](https://docs.isnap.ai/guides/managing-lines.md): Read a line you own, attach metadata to it, configure and watch it, change its variant, transfer it and end it, with the effect of each operation on billing and events.
- [Trials](https://docs.isnap.ai/guides/trials.md): Let a prospect exchange messages with a line reserved for trials, from their own phone, while your backend sends with a trial key that reaches only that prospect.
- [Webhooks overview](https://docs.isnap.ai/webhooks/overview.md): Describes how to subscribe a URL to iSnap events, what your endpoint must do, and what each delivery contains.
- [Event catalog](https://docs.isnap.ai/webhooks/event-catalog.md): Describes the envelope every event shares, lists the 37 event types by family, and lists the changes that produce no event.
- [Verifying signatures](https://docs.isnap.ai/webhooks/verifying-signatures.md): Explains how to verify the signature of every request iSnap sends to your endpoint, with the SDK, Node.js or Python, and gives a test vector to check your code.
- [Delivery guarantees](https://docs.isnap.ai/webhooks/delivery.md): States what iSnap guarantees when it delivers an event: duplicates, order, retries, suspension, replays, secret rotation and retention.
- [Events feed](https://docs.isnap.ai/webhooks/pulling-events.md): Lists the events of the last 72 hours that matched a subscription of your account, and shows a scheduled poll that catches up after an outage.
- [Message events](https://docs.isnap.ai/webhooks/events/message.md): Gives the data of message.queued, message.scheduled, message.sent, message.delivered, message.read, message.failed, message.received, message.cancelled and message.fallback_triggered, with an example of each and the personal data they carry.
- [Reaction events](https://docs.isnap.ai/webhooks/events/reaction.md): Gives the data of reaction.added, reaction.received and reaction.removed, with an example of each and the personal data they carry.
- [Typing indicator events](https://docs.isnap.ai/webhooks/events/typing-indicator.md): Gives the data of typing_indicator.started and typing_indicator.stopped, which only a line whose device detects typing sends, with an example of each and the personal data they carry.
- [Line events](https://docs.isnap.ai/webhooks/events/line.md): Gives the data of line.connected, line.disconnected, line.offline, line.degraded, line.apple_id_flagged, line.quota_warning, line.quota_exceeded, line.capability_changed, line.terminated, line.variant_changed, line.variant_scheduled and line.variant_unscheduled, with the line kinds each one concerns…
- [Trial events](https://docs.isnap.ai/webhooks/events/trial.md): Gives the data of trial.linked, trial.dormant, trial.reactivated, trial.bind_conflict and trial.revoked, with an example of each and the personal data they carry.
- [Pre-order events](https://docs.isnap.ai/webhooks/events/pre-order.md): Gives the data of pre_order.fulfilled and pre_order.cancelled, with an example of each and the personal data they carry.
- [Hosted macOS session events](https://docs.isnap.ai/webhooks/events/macos-session.md): Gives the data of macos_session.rented and macos_session.released, with an example of each.
- [Binding events](https://docs.isnap.ai/webhooks/events/binding.md): Gives the data of binding.released, the event that announces the end of a binding on a shared line, with an example and the personal data it carries.
- [Webhook events](https://docs.isnap.ai/webhooks/events/webhook.md): Gives the data of webhook.test, the probe iSnap sends to a suspended subscription, with its headers and an example.
- [TypeScript SDK](https://docs.isnap.ai/sdk/overview.md): Gives the install commands of @isnap/sdk 2.2.1, its runtime, module and TypeScript requirements, and a first call to the iSnap API with it.
- [SDK configuration](https://docs.isnap.ai/sdk/configuration.md): Lists every option of the ISnapClient constructor and of a single call with its default and validation, the headers the SDK sends, and how to call an operation that has no method.
- [SDK errors and retries](https://docs.isnap.ai/sdk/errors.md): Lists the error classes and connection-error messages of the SDK, the failures it retries by itself and for how long, how it sets idempotency keys, and how to cancel a call.
- [SDK pagination](https://docs.isnap.ai/sdk/pagination.md): Explains the four list iterators of the SDK, their page sizes, how an iteration ends, stops or fails, how to page by hand with a cursor, and which list methods return one page or the whole set.
- [SDK webhook verification](https://docs.isnap.ai/sdk/webhooks.md): Shows how to verify a webhook delivery with verifyWebhook, read the event it returns, narrow it with the nine type guards, and write a handler for the Node.js http module or a fetch-style Request.
- [SDK method reference](https://docs.isnap.ai/sdk/reference.md): Maps every SDK method to the operation it calls and what it resolves with, and describes the attachments helper, the health and version calls, and the exported names and constants.
- [Example: sending a message](https://docs.isnap.ai/sdk/examples/send-message.md): Gives a complete script that sends one message with the SDK, with an idempotency key to reuse on a retry and the handling of each error class.
- [Example: handling webhooks](https://docs.isnap.ai/sdk/examples/handle-webhooks.md): Gives a complete Node.js server that verifies webhook deliveries with the SDK, skips the event_id values it has already processed, and handles two message events.
- [Example: uploading an attachment](https://docs.isnap.ai/sdk/examples/upload-attachment.md): Gives two complete scripts that upload a file with the SDK: one with the attachments helper followed by a send, and one that runs the three steps itself and keeps the attachment id.
- [Example: listing messages](https://docs.isnap.ai/sdk/examples/list-messages.md): Gives a complete script that walks the outbound messages of the last 24 hours with the list iterator of the SDK and counts them by status.
- [API reference](https://docs.isnap.ai/api-reference/introduction.md): Lists every operation of the iSnap API with the credential it accepts, and gives the base URL, the response conventions, the compatibility rules and the OpenAPI document.
- [Changelog](https://docs.isnap.ai/changelog.md): Lists what each version of the iSnap API changed in the contract, newest first, from the first version these docs covered.
- [Send a message](https://docs.isnap.ai/api-reference/messages/send-message.md): Sends one message to one phone number from one of your lines, and returns it as queued or held.
- [List messages](https://docs.isnap.ai/api-reference/messages/list-messages.md): Lists the inbound and outbound messages that iSnap keeps, newest first, with filters and a cursor.
- [Get a message](https://docs.isnap.ai/api-reference/messages/get-message.md): Returns one message with its current status.
- [Cancel a message](https://docs.isnap.ai/api-reference/messages/cancel-message.md): Cancels a queued or held message that the line's device has not taken.
- [Add a reaction](https://docs.isnap.ai/api-reference/messages/add-reaction.md): Puts the line's reaction on a message of the line, or replaces the reaction already there.
- [Remove a reaction](https://docs.isnap.ai/api-reference/messages/remove-reaction.md): Removes the line's reaction from a message.
- [List chats](https://docs.isnap.ai/api-reference/chats/list-chats.md): Lists the chats of the lines you own, most recent activity first, with a cursor.
- [Get a chat](https://docs.isnap.ai/api-reference/chats/get-chat.md): Returns one chat: the exchange between one of your lines and one contact.
- [Mark a chat as read](https://docs.isnap.ai/api-reference/chats/mark-chat-read.md): Sets read_at on the unread inbound messages of a chat and asks the line's device to send read receipts.
- [Show the typing indicator](https://docs.isnap.ai/api-reference/chats/start-typing.md): Asks the line's device to show the typing indicator to the contact of a chat for 15 seconds.
- [Clear the typing indicator](https://docs.isnap.ai/api-reference/chats/stop-typing.md): Asks the line's device to clear the typing indicator of a chat before it expires.
- [Send a contact card](https://docs.isnap.ai/api-reference/chats/share-contact-card.md): Builds a contact card from the fields of the request and sends it to the contact of a chat as a message.
- [Create an attachment](https://docs.isnap.ai/api-reference/attachments/create-attachment.md): Registers a file and returns a signed URL to upload it, valid 15 minutes.
- [Get an attachment](https://docs.isnap.ai/api-reference/attachments/get-attachment.md): Returns an attachment and, when it is ready, a download URL valid 15 minutes.
- [Look up a recipient](https://docs.isnap.ai/api-reference/lookup/look-up-recipient.md): Tells whether a phone number or an email address can receive iMessage.
- [List available lines](https://docs.isnap.ai/api-reference/lines/list-available-lines.md): Lists the lines that can be acquired now, with masked phone numbers.
- [Get a line](https://docs.isnap.ai/api-reference/lines/get-line.md): Returns one rented or BYOD line, with its phone number masked unless the caller owns the line.
- [List your active and reserved lines](https://docs.isnap.ai/api-reference/lines/list-my-lines.md): Lists the lines of your account whose status is active or reserved.
- [Update the metadata or billing anchor of a line](https://docs.isnap.ai/api-reference/lines/update-line.md): Merges metadata into a line you own, and sets or clears its billing anchor.
- [Reserve a line](https://docs.isnap.ai/api-reference/lines/reserve-line.md): Reserves an available line for your account for 15 minutes.
- [Activate a reserved line](https://docs.isnap.ai/api-reference/lines/activate-line.md): Turns a line you reserved into an active line.
- [Release a reserved line](https://docs.isnap.ai/api-reference/lines/release-line.md): Gives back a line you reserved, which becomes available again.
- [Assign a line](https://docs.isnap.ai/api-reference/lines/assign-line.md): Makes one available line of a kind yours and activates it, in one call.
- [Create a shared line](https://docs.isnap.ai/api-reference/lines/create-shared-line.md): Creates a shared line, which is active immediately.
- [Terminate a line](https://docs.isnap.ai/api-reference/lines/terminate-line.md): Ends an active or suspended line you own, immediately and for good.
- [Cancel a line at its next anniversary](https://docs.isnap.ai/api-reference/lines/cancel-line.md): Schedules the end of a line at its next anniversary.
- [Uncancel a line](https://docs.isnap.ai/api-reference/lines/uncancel-line.md): Withdraws the scheduled end of a line.
- [Set the anniversary of a line](https://docs.isnap.ai/api-reference/lines/set-line-anniversary.md): Records when your account took a line, which sets the day a scheduled cancellation ends it.
- [Change the variant of a line](https://docs.isnap.ai/api-reference/lines/change-line-variant.md): Moves a rented line between inbound-only and two-way, immediately or at a billing anchor of the line.
- [Withdraw a scheduled variant change](https://docs.isnap.ai/api-reference/lines/cancel-variant-change.md): Withdraws the variant change that is scheduled on a line.
- [Convert a line to a test line](https://docs.isnap.ai/api-reference/lines/convert-to-test-line.md): Turns an active two-way rented line into a test line.
- [Convert a test line back to a rented line](https://docs.isnap.ai/api-reference/lines/convert-from-test-line.md): Turns an active test line back into a rented line.
- [Transfer a line to another account](https://docs.isnap.ai/api-reference/lines/transfer-line.md): Moves a line you own to another iSnap account, immediately and without the acceptance of that account.
- [Get the configuration of a line](https://docs.isnap.ai/api-reference/lines/get-line-config.md): Returns the send configuration in force on a line, the keys that are overridden, and the default and bounds of eight of its limits.
- [Update the configuration of a line](https://docs.isnap.ai/api-reference/lines/update-line-config.md): Sets per-line overrides of the send configuration of a line.
- [Get the sending limits of a line](https://docs.isnap.ai/api-reference/lines/get-line-sending-limits.md): Returns the five sending counters of a line with their limits, the reply-lane budget and the time each full counter frees room.
- [List the queue of a line](https://docs.isnap.ai/api-reference/lines/get-line-queue.md): Lists a line's outbound messages that are held, waiting for its device, or sent without a delivery receipt, with a summary of its counters.
- [Get the health of a BYOD line](https://docs.isnap.ai/api-reference/lines/get-line-health.md): Returns what the device of a BYOD line last reported.
- [List the lines that need attention](https://docs.isnap.ai/api-reference/lines/list-attention.md): Lists the lines of your account that have a fault at the time of the call, with the reasons of each BYOD line.
- [Create a webhook subscription](https://docs.isnap.ai/api-reference/webhooks/create-webhook.md): Creates a subscription for a URL and an event filter, and returns its signing secret once.
- [List webhook subscriptions](https://docs.isnap.ai/api-reference/webhooks/list-webhooks.md): Returns every webhook subscription of your account in one response, newest first, without their secrets.
- [Get a webhook subscription](https://docs.isnap.ai/api-reference/webhooks/get-webhook.md): Returns one webhook subscription of your account, without its secret.
- [Update a webhook subscription](https://docs.isnap.ai/api-reference/webhooks/update-webhook.md): Changes the URL, the event filter, the line filter, the description or the active flag of a webhook subscription.
- [Delete a webhook subscription](https://docs.isnap.ai/api-reference/webhooks/delete-webhook.md): Deletes a webhook subscription, its signing secret and its delivery records.
- [Rotate a signing secret](https://docs.isnap.ai/api-reference/webhooks/rotate-webhook-secret.md): Replaces the signing secret of a webhook subscription and returns the new one once.
- [List the deliveries of a webhook subscription](https://docs.isnap.ai/api-reference/webhooks/list-webhook-deliveries.md): Lists the delivery records of a webhook subscription, newest first, with a cursor.
- [Replay a delivery](https://docs.isnap.ai/api-reference/webhooks/replay-webhook-delivery.md): Creates a new delivery of the event of a finished delivery, to the current URL of the subscription.
- [List the events feed](https://docs.isnap.ai/api-reference/webhooks/list-webhook-events.md): Lists the events of the last 72 hours that matched a subscription of your account, newest first, with a cursor.
- [Start a trial](https://docs.isnap.ai/api-reference/trials/start-trial.md): Starts a trial on a pool line and returns the pairing code that the prospect texts to that line.
- [Get the pairing status of a trial](https://docs.isnap.ai/api-reference/trials/get-trial-status.md): Reads a trial by its pairing code, without a credential, and returns the trial key once after pairing.
- [Get the activity of a trial](https://docs.isnap.ai/api-reference/trials/get-trial-activity.md): Returns the status of a trial, its message counts and the sends left before it becomes dormant.
- [Get a trial](https://docs.isnap.ai/api-reference/trials/get-trial.md): Returns one trial that your account owns, with its metadata.
- [Update the metadata of a trial](https://docs.isnap.ai/api-reference/trials/update-trial.md): Merges metadata into a trial that your account owns.
- [Revoke a trial](https://docs.isnap.ai/api-reference/trials/revoke-trial.md): Ends a trial that your account owns, frees the prospect's handle and disables the trial key.
- [Issue a BYOD activation code](https://docs.isnap.ai/api-reference/byod/start-byod-pairing.md): Issues a single-use activation code, valid for 5 minutes, and the links to the installers of the bridge app.
- [Get the bridge app downloads](https://docs.isnap.ai/api-reference/byod/get-app-downloads.md): Returns, for macOS and for Android, the link to the installer of the bridge app, its published version and whether an installer is offered.
- [Create a pre-order](https://docs.isnap.ai/api-reference/pre-orders/create-pre-order.md): Creates a draft pre-order for one rented iMessage line, which has no effect until you confirm it.
- [List pre-orders](https://docs.isnap.ai/api-reference/pre-orders/list-pre-orders.md): Lists the pre-orders of your account, newest first, one page at a time.
- [Get a pre-order](https://docs.isnap.ai/api-reference/pre-orders/get-pre-order.md): Returns one pre-order of your account.
- [Update the metadata of a pre-order](https://docs.isnap.ai/api-reference/pre-orders/update-pre-order.md): Merges metadata into a pre-order of your account.
- [Confirm a pre-order](https://docs.isnap.ai/api-reference/pre-orders/confirm-pre-order.md): Commits a draft pre-order: the build of the line starts immediately for a wholesale partner, and once the first month is paid for a direct account.
- [Cancel a pre-order](https://docs.isnap.ai/api-reference/pre-orders/cancel-pre-order.md): Cancels a pre-order whose build has not started: a draft, or a pre-order whose first month is not paid.
- [List area codes](https://docs.isnap.ai/api-reference/pre-orders/list-area-codes.md): Lists the area codes that can be requested on a pre-order, and the countries they belong to.
- [Rent a hosted macOS session](https://docs.isnap.ai/api-reference/macos-sessions/rent-macos-session.md): Rents one hosted macOS session from iSnap's stock for a wholesale partner.
- [Get a hosted macOS session](https://docs.isnap.ai/api-reference/macos-sessions/get-macos-session.md): Returns one hosted macOS session that your account rents.
- [Update the metadata of a hosted macOS session](https://docs.isnap.ai/api-reference/macos-sessions/update-macos-session.md): Merges metadata into a hosted macOS session that your account rents.
- [Cancel a hosted macOS session at its next anniversary](https://docs.isnap.ai/api-reference/macos-sessions/cancel-macos-session.md): Schedules the end of the rental of a hosted macOS session at its next anniversary.
- [Uncancel a hosted macOS session](https://docs.isnap.ai/api-reference/macos-sessions/uncancel-macos-session.md): Withdraws the scheduled end of the rental of a hosted macOS session.
- [Get the health of the API](https://docs.isnap.ai/api-reference/service/get-health.md): Reports whether the iSnap API and its dependencies respond, without a credential.
- [Get the version of the API](https://docs.isnap.ai/api-reference/service/get-version.md): Returns the version of the iSnap API, without a credential.

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.