Campaigns

Add recipients

Up to 1,000 per call. Recipients are held to the rules POST /v2/messages holds to to. Validation happens in two steps with different outcomes:

The request as a whole. A phone number written with spaces, dashes, dots or parentheses after its + is read as the E.164 number first. Then a recipient that is not a phone number, email address, BSUID or chat id makes the whole request 400, with details.errors[].path naming it (["contacts", 2, "recipient"]); so do 8-15 bare digits on an sms, sms_oneway, whatsapp, voice or smart campaign, with details.errors[].suggestion (+<digits>), as a send refuses them. Nothing is added.
Each recipient against the campaign. A well-formed recipient the campaign cannot reach is skipped and reported in invalid and errors[{recipient, reason, code?}]: code: "unreachable_by_channel" for an email address on a phone campaign or a phone number on an email campaign; code: "ten_dlc_required" for a US/Canadian (+1) number on an sms or sms_oneway campaign while this project has no approved 10DLC campaign (the send would refuse it, as POST /v2/messages answers 403 ten_dlc_required). Repeats of a recipient already in the campaign or in the same call are skipped as duplicates. The others are added, and the call answers 201.

So 201 can mean some were not added: check invalid. A campaign that is not a draft answers 409 invalid_status.

POST

campaigns

{campaignId}

recipients

Add recipients

curl --request POST \
  --url https://api.zavu.dev/v2/campaigns/{campaignId}/recipients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contacts": [
    {
      "recipient": "+14155551234",
      "templateVariables": {
        "1": "John",
        "2": "ORD-12345"
      },
      "templateButtonVariables": {
        "0": "abc-report-token"
      },
      "templateHeaderVariables": {
        "1": "Jorge y Laura"
      }
    }
  ]
}
'

import requests

url = "https://api.zavu.dev/v2/campaigns/{campaignId}/recipients"

payload = { "contacts": [
        {
            "recipient": "+14155551234",
            "templateVariables": {
                "1": "John",
                "2": "ORD-12345"
            },
            "templateButtonVariables": { "0": "abc-report-token" },
            "templateHeaderVariables": { "1": "Jorge y Laura" }
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    contacts: [
      {
        recipient: '+14155551234',
        templateVariables: {'1': 'John', '2': 'ORD-12345'},
        templateButtonVariables: {'0': 'abc-report-token'},
        templateHeaderVariables: {'1': 'Jorge y Laura'}
      }
    ]
  })
};

fetch('https://api.zavu.dev/v2/campaigns/{campaignId}/recipients', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.zavu.dev/v2/campaigns/{campaignId}/recipients",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'contacts' => [
        [
                'recipient' => '+14155551234',
                'templateVariables' => [
                                '1' => 'John',
                                '2' => 'ORD-12345'
                ],
                'templateButtonVariables' => [
                                '0' => 'abc-report-token'
                ],
                'templateHeaderVariables' => [
                                '1' => 'Jorge y Laura'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.zavu.dev/v2/campaigns/{campaignId}/recipients"

	payload := strings.NewReader("{\n  \"contacts\": [\n    {\n      \"recipient\": \"+14155551234\",\n      \"templateVariables\": {\n        \"1\": \"John\",\n        \"2\": \"ORD-12345\"\n      },\n      \"templateButtonVariables\": {\n        \"0\": \"abc-report-token\"\n      },\n      \"templateHeaderVariables\": {\n        \"1\": \"Jorge y Laura\"\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.zavu.dev/v2/campaigns/{campaignId}/recipients")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"contacts\": [\n    {\n      \"recipient\": \"+14155551234\",\n      \"templateVariables\": {\n        \"1\": \"John\",\n        \"2\": \"ORD-12345\"\n      },\n      \"templateButtonVariables\": {\n        \"0\": \"abc-report-token\"\n      },\n      \"templateHeaderVariables\": {\n        \"1\": \"Jorge y Laura\"\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.zavu.dev/v2/campaigns/{campaignId}/recipients")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"contacts\": [\n    {\n      \"recipient\": \"+14155551234\",\n      \"templateVariables\": {\n        \"1\": \"John\",\n        \"2\": \"ORD-12345\"\n      },\n      \"templateButtonVariables\": {\n        \"0\": \"abc-report-token\"\n      },\n      \"templateHeaderVariables\": {\n        \"1\": \"Jorge y Laura\"\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "added": 123,
  "duplicates": 123,
  "invalid": 123,
  "errors": [
    {
      "recipient": "<string>",
      "reason": "<string>",
      "code": "unreachable_by_channel"
    }
  ]
}

{
  "code": "invalid_request",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "path": [
          "<string>"
        ],
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}

{
  "code": "invalid_request",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "path": [
          "<string>"
        ],
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}

{
  "code": "invalid_request",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "path": [
          "<string>"
        ],
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}

{
  "code": "invalid_request",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "path": [
          "<string>"
        ],
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

campaignId

string

required

Campaign ID. The same ID works as broadcastId on /v1.

Body

application/json

contacts

object[]

required

List of contacts to add (max 1000 per request).

Maximum array length: 1000

Show child attributes

Response

Processed. added + duplicates + invalid equals the number sent.

added

integer

required

Number of contacts successfully added.

duplicates

integer

required

Number of duplicate contacts skipped.

invalid

integer

required

Number of invalid contacts rejected.

errors

object[]

Details about invalid contacts.

Show child attributes

⌘I

Add recipients

curl --request POST \
  --url https://api.zavu.dev/v2/campaigns/{campaignId}/recipients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contacts": [
    {
      "recipient": "+14155551234",
      "templateVariables": {
        "1": "John",
        "2": "ORD-12345"
      },
      "templateButtonVariables": {
        "0": "abc-report-token"
      },
      "templateHeaderVariables": {
        "1": "Jorge y Laura"
      }
    }
  ]
}
'

import requests

url = "https://api.zavu.dev/v2/campaigns/{campaignId}/recipients"

payload = { "contacts": [
        {
            "recipient": "+14155551234",
            "templateVariables": {
                "1": "John",
                "2": "ORD-12345"
            },
            "templateButtonVariables": { "0": "abc-report-token" },
            "templateHeaderVariables": { "1": "Jorge y Laura" }
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    contacts: [
      {
        recipient: '+14155551234',
        templateVariables: {'1': 'John', '2': 'ORD-12345'},
        templateButtonVariables: {'0': 'abc-report-token'},
        templateHeaderVariables: {'1': 'Jorge y Laura'}
      }
    ]
  })
};

fetch('https://api.zavu.dev/v2/campaigns/{campaignId}/recipients', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.zavu.dev/v2/campaigns/{campaignId}/recipients",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'contacts' => [
        [
                'recipient' => '+14155551234',
                'templateVariables' => [
                                '1' => 'John',
                                '2' => 'ORD-12345'
                ],
                'templateButtonVariables' => [
                                '0' => 'abc-report-token'
                ],
                'templateHeaderVariables' => [
                                '1' => 'Jorge y Laura'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.zavu.dev/v2/campaigns/{campaignId}/recipients"

	payload := strings.NewReader("{\n  \"contacts\": [\n    {\n      \"recipient\": \"+14155551234\",\n      \"templateVariables\": {\n        \"1\": \"John\",\n        \"2\": \"ORD-12345\"\n      },\n      \"templateButtonVariables\": {\n        \"0\": \"abc-report-token\"\n      },\n      \"templateHeaderVariables\": {\n        \"1\": \"Jorge y Laura\"\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.zavu.dev/v2/campaigns/{campaignId}/recipients")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"contacts\": [\n    {\n      \"recipient\": \"+14155551234\",\n      \"templateVariables\": {\n        \"1\": \"John\",\n        \"2\": \"ORD-12345\"\n      },\n      \"templateButtonVariables\": {\n        \"0\": \"abc-report-token\"\n      },\n      \"templateHeaderVariables\": {\n        \"1\": \"Jorge y Laura\"\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.zavu.dev/v2/campaigns/{campaignId}/recipients")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"contacts\": [\n    {\n      \"recipient\": \"+14155551234\",\n      \"templateVariables\": {\n        \"1\": \"John\",\n        \"2\": \"ORD-12345\"\n      },\n      \"templateButtonVariables\": {\n        \"0\": \"abc-report-token\"\n      },\n      \"templateHeaderVariables\": {\n        \"1\": \"Jorge y Laura\"\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "added": 123,
  "duplicates": 123,
  "invalid": 123,
  "errors": [
    {
      "recipient": "<string>",
      "reason": "<string>",
      "code": "unreachable_by_channel"
    }
  ]
}

{
  "code": "invalid_request",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "path": [
          "<string>"
        ],
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}

{
  "code": "invalid_request",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "path": [
          "<string>"
        ],
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}

{
  "code": "invalid_request",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "path": [
          "<string>"
        ],
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}

{
  "code": "invalid_request",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "path": [
          "<string>"
        ],
        "message": "<string>",
        "code": "<string>"
      }
    ]
  }
}

API v2

API v2 reference

Add recipients

Authorizations

Path Parameters

Body

Response