DEV Community

Cover image for How to Check if a Phone Number is Registered with iMessage Using Google Sheets and the Blooio API
David Harvey
David Harvey

Posted on

How to Check if a Phone Number is Registered with iMessage Using Google Sheets and the Blooio API

#javascript #tutorial #imessages #ios

For sales, marketing, and outreach teams, knowing whether a prospect uses iMessage or standard SMS is a game-changer. Delivering a "blue bubble" message gives you access to read receipts, typing indicators, high-quality media sharing, and generally higher engagement rates — features that simply don't exist with regular SMS.

But how do you check if a phone number is registered with iMessage across a list of hundreds of contacts without manually typing them into your iPhone?

In this tutorial, you'll learn how to build a custom Google Sheets function using Google Apps Script and the Blooio API to automatically detect iMessage availability for any phone number or Apple ID email — at scale.

By the end of this guide, you'll be able to type =CHECKIMESSAGE(A2) into any cell and instantly know if that contact is iMessage-ready.

Why iMessage Detection Matters for Sales and Marketing

Understanding whether your prospects are on iMessage vs. SMS isn't just a nice-to-have — it directly impacts your outreach strategy:

  • iMessage users get rich media, read receipts, and higher open rates — ideal for high-touch B2B sales.
  • SMS fallback is universal and works for everyone else.
  • Routing messages correctly reduces costs and increases deliverability.

This is especially powerful when combined with a tool like Blooio, a cloud-hosted messaging API that bridges automation platforms and native Apple iMessage — letting you send and receive iMessages programmatically without needing a physical Mac or iPhone constantly active.

Prerequisites

Before you start, make sure you have the following:

  1. A Google account (for Google Sheets and Google Apps Script).
  2. A list of phone numbers or Apple ID emails to check.
  3. A Blooio account and API Key — you can grab your key from the Blooio dashboard. (Blooio is a cloud-hosted messaging API that bridges the gap between automation tools and native Apple iMessage.)

Step 1: Set Up Your Google Sheet

Head to sheets.new to instantly create a new Google Sheet. Add a column of phone numbers in Column A and label Column B as "iMessage Status".

Don't worry if your numbers are formatted messily (e.g., with dashes, spaces, or country codes) — our script will normalize them automatically into the E.164 format that APIs prefer.

screenshot of a simple Google Sheet with a

Step 2: Open Google Apps Script

Google Apps Script is a JavaScript-based cloud scripting platform that lets you extend Google Workspace products like Sheets, Docs, and Gmail. It supports custom functions in Google Sheets — meaning you can write your own formulas just like =SUM() or =VLOOKUP().

From your Google Sheet, navigate to the top menu and click:

Extensions > Apps Script

This opens a new browser tab with the Apps Script editor. Clear any default code in the Code.gs file.

screenshot of the blank Google Apps Script editor window

Step 3: Add the Blooio iMessage Detection Code

Copy and paste the following JavaScript into your Apps Script editor.

Important: Replace 'YOUR_BLOOIO_API_KEY_HERE' with your actual Blooio API key, which you can find in your Blooio dashboard.

/**
 * Normalize a US phone number string to E.164 (+1XXXXXXXXXX).
 */
function normalizeToE164US(input) {
  if (typeof input !== 'string') input = String(input || '');
  let s = input.trim();

  // Already E.164 format
  if (/^\+1\d{10}$/.test(s)) return s;

  // Remove extensions like ext.123, x123, #123
  s = s.replace(/\s*(ext\.?|x|#)\s*\d+\s*$/i, '');

  // Remove non-digits
  const digits = s.replace(/\D/g, '');

  // Handle 10 or 11-digit US numbers
  if (digits.length === 11 && digits.startsWith('1')) return '+1' + digits.slice(1);
  if (digits.length === 10) return '+1' + digits;

  // Handle something like "+1 707 653 2043"
  const plusDigits = s.replace(/\s+/g, '');
  if (/^\+1\d{10}$/.test(plusDigits)) return plusDigits;

  return null;
}

/**
 * Calls the Blooio API and returns if iMessage is available.
 */
function fetchImessageAvailability_(contact) {
  const API_KEY = 'YOUR_BLOOIO_API_KEY_HERE'; // Replace with your actual key from https://app.blooio.com
  const BASE_URL = 'https://backend.blooio.com/v1/api/contacts/';
  const endpoint = encodeURIComponent(contact);
  const url = BASE_URL + endpoint + '/capabilities';

  const options = {
    method: 'get',
    headers: {
      Authorization: 'Bearer ' + API_KEY,
      Accept: 'application/json',
    },
    muteHttpExceptions: true,
  };

  try {
    const resp = UrlFetchApp.fetch(url, options);
    const code = resp.getResponseCode();
    const text = resp.getContentText();

    if (code === 200) {
      const data = JSON.parse(text);
      return data?.capabilities?.imessage
        ? 'iMessage available'
        : 'iMessage not available';
    }

    if (code === 404) return 'Not Found';
    return 'API Error: ' + code + ' - ' + text.substring(0, 100) + '...';
  } catch (e) {
    return 'Request Failed: ' + (e && e.message ? e.message : String(e));
  }
}

/**
 * Custom Google Sheets function to check if a phone number or email is registered with iMessage.
 *
 * Example: =CHECKIMESSAGE(A2)
 *
 * @param {string} contact Phone number or Apple ID email.
 * @return {string} "iMessage available" / "iMessage not available" / error message.
 * @customfunction
 */
function CHECKIMESSAGE(contact) {
  if (!contact) return '';

  const str = String(contact).trim();

  // Handle Apple ID email addresses directly
  if (str.includes('@')) {
    return fetchImessageAvailability_(str);
  }

  // Normalize phone numbers to E.164
  const e164 = normalizeToE164US(str);
  if (!e164) {
    return "Error: Couldn't parse as a US phone number or email.";
  }

  return fetchImessageAvailability_(e164);
}
Enter fullscreen mode Exit fullscreen mode

Once pasted, click the Save icon (the floppy disk) or press Cmd+S / Ctrl+S.

Step 4: Test Your New Custom Function

Head back to your Google Sheet. In cell B2, type:

=CHECKIMESSAGE(A2)
Enter fullscreen mode Exit fullscreen mode

Hit Enter. The cell will briefly show Loading... while it calls the Blooio API, then return one of these results:

Result Meaning
iMessage available The number/email is registered with iMessage
iMessage not available The contact uses standard SMS (Android or SMS-only)
Not Found The number isn't recognized
Error: ... A parsing or network issue occurred

Once it works for one cell, drag the formula down column B to enrich your entire list in seconds.

iMessages status of every number in Google Sheets

How It Works Under the Hood

1. Phone Number Normalization

The normalizeToE164US() function cleans up messy CRM data — stripping out extensions, dashes, spaces, and country code prefixes — converting everything into the standard E.164 format (+1XXXXXXXXXX) that REST APIs expect.

2. Blooio /capabilities API Call

The script calls Blooio's /capabilities endpoint, passing either a normalized phone number or an Apple ID email address. This is the same endpoint used by Blooio's messaging infrastructure to determine how to route a message before sending it.

You can explore Blooio's full pricing and feature set to understand what else is possible — including programmatic iMessage sending, read receipt tracking, and SMS fallback.

3. Response Parsing

The script checks the capabilities.imessage boolean in the JSON response and converts it to a human-readable label ("iMessage available" or "iMessage not available") directly inside your spreadsheet cell.

Scaling This Up: Tips for Large Lists

If you're running this against thousands of rows, keep these Google Apps Script best practices in mind:

  • Batch API calls — avoid calling the API on every cell individually; consider a trigger-based batch function instead.
  • Cache results — use CacheService to store results for numbers you've already checked.
  • Rate limiting — respect API rate limits; add a Utilities.sleep() call between requests for large batches.
  • Error handling — the script already handles 404s and network failures gracefully, but log unexpected errors to a separate sheet for review.

Wrapping Up

By connecting Google Sheets and Google Apps Script with the Blooio API, you've built a lightweight but powerful CRM enrichment tool for iMessage detection.

Sales teams can now confidently segment their outreach:

  • Send rich media, reactions, and read-receipt-enabled messages to iMessage users via Blooio.
  • Fall back to standard A2P SMS for Android and non-Apple contacts.

This kind of contact intelligence — knowing before you send whether someone is reachable over iMessage — is a small automation that compounds into significantly better deliverability and engagement over time.

Ready to get started? Create your free Blooio account and grab your API key.

Have you built any other automations around iMessage, RCS, or SMS routing? Drop a comment below — I'd love to see what you're building!

Top comments (0)