URL Verification

URL verification ensures that links in your SMS and email messages are safe and compliant. All URLs in SMS and email messages must be verified before the message can be sent.

Why URL Verification?

Carriers and email providers actively filter messages containing malicious or suspicious links. URL verification helps you:

• Prevent delivery failures - Messages with unverified or blocked URLs won't be delivered
• Protect your reputation - Avoid being flagged as a spam sender
• Ensure compliance - Meet carrier requirements for SMS messaging
• Block malicious links - Automatic detection of phishing and malware sites

How It Works

1. Extract URLs

   When you send a message, Zavu extracts all URLs from the content

2. Check Verification Status

   Each URL is checked against your verified URLs list

3. Automatic Verification

   New URLs are automatically verified against Google Web Risk API

4. Delivery Decision

   Safe URLs are approved; malicious URLs block the message

URL Verification Status

Pre-Verifying URLs

Submit URLs for verification before using them in messages:

TypeScriptcURLCopy
import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev();

const result = await zavu.urls.submitForVerification({
  url: "https://mystore.example.com/sale",
});

console.log(`URL ID: ${result.url.id}`);
console.log(`Status: ${result.url.status}`); // "approved" for safe URLs
console.log(`Domain: ${result.url.domain}`);

Approved Response

JSONCopy
{
  "url": {
    "id": "url_abc123",
    "url": "https://mystore.example.com/sale",
    "domain": "mystore.example.com",
    "status": "approved",
    "approvalType": "auto_web_risk",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Blocked URLs

URL Shorteners

URL shorteners are always blocked because they hide the destination URL:

terminalCopy
# These will be rejected
bit.ly/abc123
t.co/xyz789
tinyurl.com/short

Malicious URLs

URLs flagged by Google Web Risk as malicious are automatically blocked:

JSONCopy
{
  "code": "url_malicious",
  "message": "URL has been flagged as potentially harmful by security systems",
  "details": {
    "urls": ["https://malicious-site.example"],
    "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"],
    "warning": "fraud_prevention"
  }
}

Listing Verified URLs

View all URLs that have been verified for your project:

TypeScriptcURLCopy
const { items, nextCursor } = await zavu.urls.listVerified({
  status: "approved",
  limit: 50,
});

for (const url of items) {
  console.log(`${url.domain}: ${url.url} (${url.status})`);
}

Response

JSONCopy
{
  "items": [
    {
      "id": "url_abc123",
      "url": "https://mystore.example.com/sale",
      "domain": "mystore.example.com",
      "status": "approved",
      "approvalType": "auto_web_risk",
      "createdAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "url_def456",
      "url": "https://mystore.example.com/products",
      "domain": "mystore.example.com",
      "status": "approved",
      "approvalType": "auto_web_risk",
      "createdAt": "2024-01-15T10:25:00.000Z"
    }
  ],
  "nextCursor": null
}

Getting URL Details

TypeScriptcURLCopy
const url = await zavu.urls.retrieveDetails("url_abc123");

console.log(`URL: ${url.url}`);
console.log(`Status: ${url.status}`);
console.log(`Verified at: ${url.createdAt}`);

Automatic Verification in Messages

When you send a message with URLs, Zavu automatically extracts and verifies them:

TypeScriptCopy
// URLs in message are automatically verified
const message = await zavu.messages.send({
  to: "+14155551234",
  text: "Check out our sale: https://mystore.example.com/sale",
});

// If URL is not pre-verified, it will be checked automatically
// If blocked, the message status will be "pending_url_verification"

Message Status: pending_url_verification

If a message contains an unverified URL that requires manual review:

JSONCopy
{
  "id": "msg_abc123",
  "to": "+14155551234",
  "status": "pending_url_verification",
  "text": "Check out: https://new-domain.example.com/page"
}

Best Practices

Domain-Level Verification

Once a URL is verified, subsequent URLs from the same domain are typically verified faster:

TypeScriptCopy
// First URL from domain - full verification
await zavu.urls.submitForVerification({ url: "https://mystore.example.com/sale" });

// Additional URLs from same domain - faster verification
await zavu.urls.submitForVerification({ url: "https://mystore.example.com/products" });
await zavu.urls.submitForVerification({ url: "https://mystore.example.com/about" });

Complete Example

TypeScriptCopy
import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev();

async function sendCampaignWithLinks() {
  const campaignUrls = [
    "https://mystore.example.com/sale",
    "https://mystore.example.com/new-arrivals",
  ];

  // 1. Pre-verify all campaign URLs
  console.log("Verifying campaign URLs...");

  for (const url of campaignUrls) {
    try {
      const result = await zavu.urls.submitForVerification({ url });
      console.log(`${url}: ${result.url.status}`);

      if (result.url.status !== "approved") {
        throw new Error(`URL not approved: ${url}`);
      }
    } catch (error) {
      console.error(`Failed to verify ${url}:`, error);
      return;
    }
  }

  // 2. Send messages with verified URLs
  console.log("\nSending campaign...");

  const message = await zavu.messages.send({
    to: "+14155551234",
    text: `Sale alert! Shop now: ${campaignUrls[0]}`,
  });

  console.log(`Message sent: ${message.id} (${message.status})`);
}

sendCampaignWithLinks();

Troubleshooting

URL Rejected

If your URL is rejected:

1. Check that it's not a URL shortener
2. Ensure the URL is accessible (not 404)
3. Verify the domain has valid SSL
4. Contact support if you believe it's a false positive

Message Stuck in pending_url_verification

1. Submit the URL manually using POST /v1/urls
2. Wait for verification (usually seconds)
3. The message will be released once approved

Malicious URL Detection

If your legitimate URL is flagged as malicious:

1. Check Google Safe Browsing for your domain
2. Resolve any security issues on your site
3. Request a review from Google
4. Contact Zavu support with the resolution details