ایک VBA میکرو کے ساتھ Excel گاہکوں کو Brevo میں کیسے پش کریں (اور Office Scripts متبادل)

آپ کے پاس Excel میں گاہک ہیں اور آپ انہیں Brevo میں چاہتے ہیں۔ تیز اور گندا جواب فائل کو .csv کے طور پر محفوظ کرنا اور اسے امپورٹ کرنا ہے، جو ایک بار کے لیے ٹھیک ہے۔ کسی بھی چیز کے لیے جو آپ بار بار کر رہے ہیں (ہفتہ وار سیلز ہینڈ آف، آپ کی ٹیم روزانہ اپڈیٹ کرنے والی ورک بک، ایک پارٹنر فہرست جو ریفریش ہوتی رہتی ہے)، آپ Excel کے اندر ایک بٹن چاہتے ہیں جو سنک کرے۔

یہ گائیڈ ان دو راستوں کا احاطہ کرتی ہے جو واقعی اس کے لیے معنی رکھتے ہیں:

1. ورک بک میں ایمبیڈڈ ایک VBA میکرو: کوئی لائسنسنگ نہیں، کوئی کلاؤڈ نہیں، آف لائن کام کرتا ہے، صارف کے بٹن پر کلک کرنے کے لمحے چلتا ہے۔ “Excel سے Brevo” کے تقریباً 80% کیسز کے لیے صحیح جواب۔
2. Office Scripts + Power Automate: VBA کے بجائے TypeScript، کلاؤڈ میں چلتا ہے، شیڈولڈ ٹریگرز کی حمایت کرتا ہے۔ صحیح جواب اگر ورک بک OneDrive/SharePoint میں رہتی ہے اور آپ بغیر نگرانی کے سنک چاہتے ہیں، لیکن Power Automate لائسنسنگ سے آگاہ رہیں۔

اگر آپ Google Sheets کا مساوی تلاش کر رہے ہیں، تو Apps Script پر ہمراہ مضمون دیکھیں۔ اور اگر آپ صرف اپنے لیپ ٹاپ پر اسکرپٹ سے ایک شاٹ CSV امپورٹ چاہتے ہیں، تو CSV امپورٹ گائیڈ میں Python، Node.js، اور cURL ورژنز ہیں۔

میکرو کیا کرتا ہے

جب صارف شیٹ پر “Sync to Brevo” بٹن پر کلک کرتا ہے:

1. ایکٹو ورک شیٹ سے ہر قطار پڑھیں (پہلے ہیڈر قطار، فی قطار ایک گاہک)۔
2. Brevo کے jsonBody پیرامیٹر کے لیے شکل والا JSON ارے بنائیں۔
3. اسے ورک بک کی محفوظ کردہ API کلید کے ساتھ https://api.brevo.com/v3/contacts/import پر POST کریں۔
4. نتیجہ کے ساتھ ایک پیغام باکس دکھائیں۔

بس اتنا ہی۔ تقریباً 120 لائنز VBA۔ نیچے مکمل، ورکنگ ماڈیول ہے۔

شیٹ کا لے آؤٹ جس کی میکرو توقع کرتا ہے

email لازمی ہے۔ ہر دوسرا کالم Brevo گاہک اٹریبیوٹ بن جاتا ہے، جسے کالم ہیڈر (بڑے حروف میں) کے ذریعے اٹریبیوٹ نام پر میپ کیا جاتا ہے۔ تو firstName → FIRSTNAME، company → COMPANY۔ کسٹم اٹریبیوٹس (معیاری سیٹ سے باہر کوئی بھی چیز) آپ کے Brevo اکاؤنٹ میں پہلے موجود ہونے چاہئیں۔ انہیں Contacts → Settings → Contact attributes کے تحت بیان کریں۔

مرحلہ 1: VBA ایڈیٹر کھولیں

Excel میں: Alt + F11 دبائیں۔ VBA ایڈیٹر کھلتا ہے۔ بائیں طرف Project پین میں، اپنی ورک بک پر دائیں کلک کریں اور Insert → Module منتخب کریں۔ ایک خالی Module1 ظاہر ہوتا ہے۔

مرحلہ 2: مکمل میکرو پیسٹ کریں

Module1 کے مواد کو اس کے ساتھ بدل دیں:

' ===========================================================================
' Brevo contact sync for Excel
' Reads the active sheet's rows and POSTs them to Brevo's import API.
' ===========================================================================
Option Explicit

Private Const BREVO_API_BASE As String = "https://api.brevo.com/v3"
Private Const BREVO_LIST_ID As Long = 42       ' <- your Brevo list ID
Private Const BATCH_SIZE As Long = 1000

' --- Public entry points (the ones you assign to ribbon buttons) -----------

Public Sub SyncSheetToBrevo()
    Dim apiKey As String
    apiKey = GetApiKey()
    If apiKey = "" Then
        MsgBox "No API key configured. Run ConfigureApiKey first.", _
               vbExclamation, "Brevo Sync"
        Exit Sub
    End If

    Dim ws As Worksheet
    Set ws = ActiveSheet

    Dim emailCol As Long
    emailCol = FindEmailColumn(ws)
    If emailCol = 0 Then
        MsgBox "Sheet must have an 'email' column in row 1.", _
               vbExclamation, "Brevo Sync"
        Exit Sub
    End If

    Dim lastRow As Long, lastCol As Long
    lastRow = ws.Cells(ws.Rows.Count, emailCol).End(xlUp).Row
    lastCol = ws.Cells(1, ws.Columns.Count).End(xlToLeft).Column
    If lastRow < 2 Then
        MsgBox "No contact rows found.", vbInformation, "Brevo Sync"
        Exit Sub
    End If

    Dim contacts As Collection
    Set contacts = New Collection

    Dim r As Long, c As Long
    For r = 2 To lastRow
        Dim email As String
        email = LCase(Trim(CStr(ws.Cells(r, emailCol).Value)))
        If email <> "" And InStr(email, "@") > 0 Then
            Dim json As String
            json = "{""email"":""" & EscapeJson(email) & """,""attributes"":{"

            Dim attrFirst As Boolean
            attrFirst = True
            For c = 1 To lastCol
                If c <> emailCol Then
                    Dim val As String
                    val = CStr(ws.Cells(r, c).Value)
                    If val <> "" Then
                        If Not attrFirst Then json = json & ","
                        Dim attrName As String
                        attrName = UCase(Trim(CStr(ws.Cells(1, c).Value)))
                        json = json & """" & attrName & """:""" & EscapeJson(val) & """"
                        attrFirst = False
                    End If
                End If
            Next c

            json = json & "}}"
            contacts.Add json
        End If
    Next r

    If contacts.Count = 0 Then
        MsgBox "No valid contact rows found.", vbInformation, "Brevo Sync"
        Exit Sub
    End If

    Dim totalSent As Long
    Dim batchNum As Long
    Dim okCount As Long, failCount As Long
    Dim batchStart As Long

    For batchStart = 1 To contacts.Count Step BATCH_SIZE
        batchNum = batchNum + 1
        Dim batchEnd As Long
        batchEnd = batchStart + BATCH_SIZE - 1
        If batchEnd > contacts.Count Then batchEnd = contacts.Count

        Dim payload As String
        payload = "{""jsonBody"":["
        Dim i As Long
        For i = batchStart To batchEnd
            If i > batchStart Then payload = payload & ","
            payload = payload & contacts(i)
        Next i
        payload = payload & "],""listIds"":[" & BREVO_LIST_ID & _
                  "],""updateExistingContacts"":true,""emptyContactsAttributes"":false}"

        Dim ok As Boolean
        ok = PostToBrevo(apiKey, payload)
        If ok Then
            okCount = okCount + 1
            totalSent = totalSent + (batchEnd - batchStart + 1)
        Else
            failCount = failCount + 1
        End If
    Next batchStart

    MsgBox "Sent " & totalSent & " contact(s) in " & batchNum & " batch(es)." _
           & vbCrLf & "Successful batches: " & okCount _
           & vbCrLf & "Failed batches: " & failCount, _
           vbInformation, "Brevo Sync"
End Sub

Public Sub ConfigureApiKey()
    Dim key As String
    key = InputBox("Paste your Brevo API key (xkeysib-...):", "Brevo API Key")
    If key = "" Then Exit Sub
    key = Trim(key)
    If Left(key, 8) <> "xkeysib-" Then
        MsgBox "That doesn't look like a Brevo API key (should start with xkeysib-).", _
               vbExclamation, "Brevo API Key"
        Exit Sub
    End If

    On Error Resume Next
    ThisWorkbook.CustomDocumentProperties("BrevoApiKey").Delete
    On Error GoTo 0

    ThisWorkbook.CustomDocumentProperties.Add _
        Name:="BrevoApiKey", _
        LinkToContent:=False, _
        Type:=msoPropertyTypeString, _
        Value:=key

    ThisWorkbook.Save
    MsgBox "API key saved inside the workbook.", vbInformation, "Brevo API Key"
End Sub

' --- Private helpers --------------------------------------------------------

Private Function GetApiKey() As String
    On Error Resume Next
    GetApiKey = ThisWorkbook.CustomDocumentProperties("BrevoApiKey").Value
    On Error GoTo 0
End Function

Private Function FindEmailColumn(ws As Worksheet) As Long
    Dim lastCol As Long, c As Long
    lastCol = ws.Cells(1, ws.Columns.Count).End(xlToLeft).Column
    For c = 1 To lastCol
        If LCase(Trim(CStr(ws.Cells(1, c).Value))) = "email" Then
            FindEmailColumn = c
            Exit Function
        End If
    Next c
    FindEmailColumn = 0
End Function

Private Function PostToBrevo(apiKey As String, payload As String) As Boolean
    Dim http As Object
    Set http = CreateObject("MSXML2.XMLHTTP")
    http.Open "POST", BREVO_API_BASE & "/contacts/import", False
    http.SetRequestHeader "api-key", apiKey
    http.SetRequestHeader "Content-Type", "application/json"
    http.SetRequestHeader "Accept", "application/json"
    http.Send payload
    PostToBrevo = (http.Status = 202)
    If Not PostToBrevo Then
        Debug.Print "Brevo error " & http.Status & ": " & http.responseText
    End If
End Function

Private Function EscapeJson(s As String) As String
    Dim r As String
    r = Replace(s, "\", "\\")
    r = Replace(r, """", "\""")
    r = Replace(r, vbCrLf, "\n")
    r = Replace(r, vbLf, "\n")
    r = Replace(r, vbCr, "\n")
    r = Replace(r, vbTab, "\t")
    EscapeJson = r
End Function

مرحلہ 3: ورک بک کو .xlsm کے طور پر محفوظ کریں

VBA میکروز صرف میکرو فعال ورک بکس میں برقرار رہتے ہیں۔ Save As → Excel Macro-Enabled Workbook (.xlsm) منتخب کریں۔ سادہ .xlsx فارمیٹ میکروز کو خاموشی سے ہٹا دیتا ہے۔ بہت سے لوگ پہلی بار اس طرح کوڈ کھو دیتے ہیں۔

مرحلہ 4: اپنی API کلید کنفیگر کریں

ConfigureApiKey کو ایک بار چلائیں۔ یا تو:

• VBA ایڈیٹر میں، ConfigureApiKey سب کے اندر کہیں بھی کلک کریں اور F5 دبائیں، یا
• Excel میں، Developer → Macros، ConfigureApiKey چنیں، Run۔

اپنی xkeysib-... کلید پیسٹ کریں۔ میکرو اسے ورک بک کے اندر ایک کسٹم ڈاکومنٹ پراپرٹی کے طور پر محفوظ کرتا ہے، یہ سورس کوڈ میں نہیں ہے، رجسٹری میں نہیں ہے، اور فائل کے ساتھ سفر کرتا ہے (تو آگاہ رہیں: اگر آپ .xlsm کسی کو ای میل کرتے ہیں، تو API کلید اس کے ساتھ جاتی ہے)۔

اگر آپ کلید کو ورک بک سے باہر کہیں رکھنا چاہتے ہیں، تو اسٹوریج کو Windows رجسٹری پر سوئپ کریں:

' Replace the body of ConfigureApiKey with:
SaveSetting "Brevo", "Sync", "ApiKey", key

' And GetApiKey with:
GetApiKey = GetSetting("Brevo", "Sync", "ApiKey", "")

SaveSetting/GetSetting HKCU\Software\VB and VBA Program Settings\Brevo\Sync کے تحت لکھتا ہے (فی صارف، فی ورک بک نہیں)۔ اسے استعمال کریں اگر متعدد ورک بکس کو ایک کلید شیئر کرنی چاہیے، یا اگر آپ کلید کو فائل میں نہیں چاہتے۔

مرحلہ 5: شیٹ پر ایک بٹن شامل کریں

یہ وہ ہے جو اسے غیر تکنیکی صارفین کے لیے ایک کلک کا تجربہ بناتا ہے۔

Insert → Shapes → Rectangle، شیٹ پر ایک ڈراپ کریں، اسے “Sync to Brevo” کا لیبل دیں۔ شکل پر دائیں کلک کریں → Assign Macro → SyncSheetToBrevo چنیں۔ ہو گیا۔

یا، زیادہ پالیشڈ UI کے لیے، Office Custom UI Editor کے ذریعے ایک کسٹم ربن ٹیب شامل کریں، لیکن زیادہ تر اندرونی ٹولز کے لیے، شکل-بطور-بٹن کافی ہے۔

مرحلہ 6: اسے چلائیں

بٹن پر کلک کریں۔ میکرو قطاریں پڑھتا ہے، انہیں بیچ کرتا ہے، ہر بیچ کو Brevo پر پوسٹ کرتا ہے، اور ایک خلاصہ پیغام باکس دکھاتا ہے۔ Brevo کا امپورٹ ایسنکرونس ہے، تو کامیابی کے پیغام کا مطلب ہے “Brevo نے بیچ قبول کر لیا”، اصل گاہک کی تخلیق سرور سائیڈ پر اگلے چند سیکنڈ میں ہوتی ہے۔ آپ کو Brevo سے ای میل خلاصہ ملے گا جب یہ ختم ہو جائے گا (جب تک کہ آپ نے disableNotification: true سیٹ نہ کیا ہو)۔

عام پھندے

بٹن کچھ نہیں کرتا اور کوئی ایرر نہیں ہے۔ میکروز غیر فعال ہیں۔ شیٹ کے اوپر پیلے سکیورٹی بار پر دیکھیں، Enable Content پر کلک کریں۔ اگر آپ کی تنظیم میکروز کو بلاک کرتی ہے، تو نیچے ٹرسٹ سینٹر / کوڈ سائننگ راستہ دیکھیں۔

Compile error: User-defined type not defined۔ آپ Mac Excel پر ہیں، جس کے پاس MSXML2.XMLHTTP نہیں ہے۔ Mac VBA براہ راست HTTPS درخواستیں نہیں کر سکتا؛ اس کے بجائے نیچے Office Scripts راستہ استعمال کریں۔

Brevo سے بغیر کسی واضح وجہ کے 400 Bad Request۔ تقریباً ہمیشہ ان میں سے ایک: (a) آپ کی شیٹ میں ایک کسٹم اٹریبیوٹ ابھی Brevo میں موجود نہیں ہے (پہلے اسے بنائیں)؛ (b) JSON ایسکیپ بگ (سیل ویلیوز میں کوٹس یا بیک سلیشز جو ایسکیپ نہیں ہوئے)۔ کوڈ میں EscapeJson فنکشن معیاری کیسز کو ہینڈل کرتا ہے؛ اگر آپ کے ڈیٹا میں عجیب حروف ہیں، تو payload کو Immediate ونڈو میں لاگ کریں (Debug.Print payload) اور معائنہ کریں۔

401 Unauthorized۔ غلط ہیڈر۔ یہ api-key ہے (چھوٹے حروف، ہائیفن)، نہ کہ Authorization۔ میکرو صحیح والا استعمال کرتا ہے، لیکن اگر آپ نے کہیں اور سے سنپٹ کاپی کیا ہے، تو دوبارہ چیک کریں۔

Excel بڑے امپورٹس پر فریز ہو جاتا ہے۔ میکرو UI تھریڈ پر سنکرونس چلتا ہے۔ 50,000+ قطاروں کے لیے، آپ Excel کو 10 سے 30 سیکنڈ تک ہینگ ہوتے دیکھیں گے جبکہ یہ JSON بناتا ہے اور Brevo کا انتظار کرتا ہے۔ یا تو اسے قبول کریں، یا MSXML2.XMLHTTP کو اس کی ایسنک قسم پر سوئچ کریں، لیکن اس پیمانے پر آپ Power Automate (اگلا سیکشن) میں بہتر ہیں۔

جب VBA کافی نہیں: Office Scripts + Power Automate

VBA شیڈولڈ کلاؤڈ سنک نہیں کر سکتا۔ اگر آپ کو ضرورت ہے:

• ورک بک ہر گھنٹے Brevo میں سنک ہو بغیر کسی کے کھولے
• ورک بک OneDrive/SharePoint میں ہو، ویب سے ایڈٹ ہو
• ایک IT ڈپارٹمنٹ جو ڈیسک ٹاپ میکروز پر پابندی لگاتا ہے

…تو آپ Office Scripts (Microsoft کا Apps Script کا کلاؤڈ مساوی) اور Power Automate (ان کی شیڈولنگ اور HTTP پرت) چاہتے ہیں۔

تقسیم: Office Scripts شیٹ کو پڑھتا ہے اور گاہک کا ڈیٹا واپس کرتا ہے۔ Power Automate وہ ڈیٹا لیتا ہے اور ٹریگر پر Brevo کو پوسٹ کرتا ہے۔

Office Script (ویب کے لیے Excel → Automate → New Script):

function main(workbook: ExcelScript.Workbook): {email: string, attributes: Record<string, string>}[] {
  const sheet = workbook.getActiveWorksheet();
  const range = sheet.getUsedRange();
  if (!range) return [];

  const values = range.getValues() as string[][];
  if (values.length < 2) return [];

  const headers = values[0].map(h => String(h).trim());
  const emailIdx = headers.findIndex(h => h.toLowerCase() === "email");
  if (emailIdx === -1) throw new Error("Sheet must have an 'email' column");

  const contacts: {email: string, attributes: Record<string, string>}[] = [];
  for (let r = 1; r < values.length; r++) {
    const row = values[r];
    const email = String(row[emailIdx] ?? "").trim().toLowerCase();
    if (!email || !email.includes("@")) continue;

    const attributes: Record<string, string> = {};
    for (let c = 0; c < headers.length; c++) {
      if (c === emailIdx) continue;
      const v = row[c];
      if (v === null || v === "") continue;
      attributes[headers[c].toUpperCase()] = String(v);
    }
    contacts.push({ email, attributes });
  }
  return contacts;
}

Power Automate فلو:

1. Trigger: Recurrence (ہر 1 گھنٹے)، یا دستی بٹن، یا “When a row is modified” اگر آپ تبدیلی پر مبنی سنک چاہتے ہیں۔
2. Action: Excel Online → Run script: اسے اپنی ورک بک اور اوپر کی اسکرپٹ پر پوائنٹ کریں۔ اس کی واپسی کی ویلیو کو contacts کے طور پر محفوظ کریں۔
3. Action: HTTP (یہ پریمیم کنیکٹر ہے، نیچے لائسنسنگ نوٹ دیکھیں)۔
   • Method: POST
   • URI: https://api.brevo.com/v3/contacts/import
   • Headers: api-key: xkeysib-...، Content-Type: application/json
   • Body:

     {
       "jsonBody": @{outputs('Run_script')?['body/result']},
       "listIds": [42],
       "updateExistingContacts": true
     }

4. Action: Condition → اگر اسٹیٹس کوڈ 202 نہیں ہے، تو Teams/ای میل الرٹ بھیجیں۔

لائسنسنگ کی حقیقت کا چیک: HTTP ایکشن ایک Power Automate Premium کنیکٹر ہے۔ Microsoft 365 Business Basic/Standard پلانز پر آپ کو معیاری کنیکٹرز ملتے ہیں لیکن پریمیم نہیں۔ سب سے سستا حل Power Automate Premium ایڈ آن ہے (لکھنے کے وقت فی صارف فی مہینہ تقریباً 15 USD)، یا HTTP کو ایک چھوٹے Azure Function میں منتقل کریں جسے معیاری فلو کال کر سکتا ہے۔ اگر آپ پہلے سے E3/E5 پر ہیں جس میں پریمیم شامل ہے، تو آپ تیار ہیں۔

یہ اہم وجہ ہے کہ Apps Script کہانی صاف ستھری ہے: Apps Script کی UrlFetchApp مفت اور بے قید ہے، جبکہ Microsoft کا مساوی نیٹ ورک کال کو ادائیگی شدہ کنیکٹر ٹائر کے پیچھے رکھتا ہے۔

VBA بمقابلہ Office Scripts بمقابلہ Apps Script: کب کیا چنیں

یہ Zapier / no-code پلیٹ فارمز کو کیوں شکست دیتا ہے

ایک بار بار چلنے والی Excel سے Brevo جاب کے لیے، تیسرے فریق آٹومیشن ٹولز (Zapier، Make، n8n) فی ٹاسک چارج کرتے ہیں اور آپ کے ڈیٹا اور Brevo کے درمیان ایک تیسرا فریق رکھتے ہیں۔ VBA اپروچ کی صفر جاری لاگت ہے، کوئی تیسرا فریق ڈیٹا فلو نہیں، اور یہ فائل کے اندر رہتی ہے (جب ورک بک منتقل ہوتی ہے، تو انضمام اس کے ساتھ منتقل ہوتا ہے)۔ Office Scripts + Power Automate ملتا جلتا ہے لیکن Microsoft تیسرے فریق کے طور پر (اگر آپ M365 پر ہیں تو پہلے ہی آپ کے اسٹیک میں)۔

Brevo کے POST /v3/contacts/import اینڈ پوائنٹ کا پورا نکتہ یہ ہے کہ آپ کو گلو پلیٹ فارم کی ضرورت نہیں، آپ کے ٹولز پہلے ہی HTTP درخواستیں بنانا جانتے ہیں۔

مزید پڑھنے کے لیے

• Brevo API: گاہک امپورٹ کریں ریفرنس
• Microsoft Office Scripts کا جائزہ
• Power Automate HTTP کنیکٹر (Premium)
• Google Sheets کے لیے Apps Script مساوی
• اسکرپٹ پر مبنی CSV/Excel امپورٹ (Python، Node.js، cURL)