ZAzavudev

Create sender

Changed on
post/v1/senders

Request

  • Base URL
    https://api.zavu.dev
  • URL
    https://api.zavu.dev/v1/senders
  • Auth
    HTTP bearer

Request body

namestring required
phoneNumberstring

Phone number in E.164 format, and it must be a number your project already owns (see GET /v1/phone-numbers). The number is routed to the sender as part of this call, which is what turns the SMS channel on. Passing a number the project does not own, one already attached to another sender, or one rejected in regulatory review returns 400 rather than creating a sender that cannot send. A number still under review is attached and starts carrying messages when it is approved. Omit for an email-only sender.

enableVoiceboolean

Let this sender place and answer phone calls. Requires phoneNumber; enabling it without one returns 400. Check the channels array on the response to confirm voice is on.

enableSmsOnewayboolean

Enable the one-way SMS channel (sms_oneway). No phone number and no credential, so it is the fastest way to get a sender that can send. Recipients cannot reply. Sending to a US or Canadian (+1) number still needs an approved 10DLC campaign, and is refused with 403 ten_dlc_required until then. Confirm with sms_oneway in the channels array on the response.

setAsDefaultboolean
webhookUrlstring uri

HTTPS URL for webhook events.

webhookEventsWebhookEvent[]

Events to subscribe to.

emailAddressstring email

From-address for the email channel (e.g. noreply@yourdomain.com). The address's domain must be a verified email domain in your project. Setting this attaches the email channel to the sender.

emailDomainIdstring

ID of the verified email domain to attach. Optional — resolved from emailAddress's domain when omitted.

emailFromNamestring

Display name shown in the recipient's inbox for the email channel.

emailReceivingEnabledboolean

Enable inbound email receiving on this sender. Requires a verified inbound MX record on the domain; the request is ignored otherwise. Read emailReceivingEnabled back off the response to see whether it was applied — it comes back false when the MX has not verified.

webhookSignatureVersion'v1' | 'v1+v2' | 'v2'

Which X-Zavu-Signature scheme this receiver is sent.

  • v1: v1=HMAC_SHA256(secret, body). The scheme used before this was configurable. Existing webhooks stay on it until you move them.
  • v2: v2=HMAC_SHA256(secret, "{t}.{body}"). The current scheme, and the default for new senders. It signs the timestamp together with the body.
  • v1+v2: both signatures, sharing one t. The migration setting: a receiver reading either one works, so you can deploy and confirm your new verifier before switching over.

Moving from v1 straight to v2 returns 400. Set v1+v2 first. See https://docs.zavu.dev/guides/receiving-messages/signature-migration

Example request

{
  "emailAddress": "noreply@yourdomain.com",
  "webhookSignatureVersion": "v2"
}

Response

Sender created.

idstring required
namestring required
phoneNumberstring

Phone number in E.164 format. Absent on a sender that has none: an email-only sender, or one created with only enableSmsOneway.

channelsstring[]

Channels this sender can actually send on right now: configured AND activated. Empty means the sender cannot send or receive anything yet: a phoneNumber alone does not enable SMS or voice, and a connected account that is not activated is left out, because every send on it is refused. Check this rather than inferring capability from phoneNumber or emailAddress, and turn a connected channel on with POST /v1/senders/{senderId}/channels/{channel}/activate.

isDefaultboolean

Whether this sender is the project's default.

emailAddressstring

From-address for the email channel, if configured.

emailReceivingEnabledboolean

Whether inbound email receiving is enabled for this sender.

emailCatchAllEnabledboolean

Whether catch-all receiving is enabled. When true (and emailReceivingEnabled is true), this sender receives email addressed to any local part at its domain, not just its own address. The original recipient is delivered in the message.inbound webhook's data.to.

createdAtstring date-time
updatedAtstring date-time

Example response

{
  "id": "sender_12345",
  "name": "Primary sender",
  "phoneNumber": "+13125551212",
  "channels": [
    "sms",
    "voice"
  ],
  "webhook": {
    "url": "https://api.example.com/webhooks/zavu",
    "secret": "whsec_abc123...",
    "signatureVersion": "v2"
  },
  "whatsapp": {
    "displayPhoneNumber": "+14155551234",
    "paymentStatus": {
      "setupStatus": "COMPLETE",
      "methodStatus": "VALID"
    }
  },
  "emailAddress": "noreply@yourdomain.com"
}

Changes

  • ce129d29ce3cRevision changes
    • warning

      added the new contact.identity_linked enum value to the // response property for the response status

    • info

      added the new contact.identity_linked enum value to the request property /

  • 358ec4c351c6Revision changes
    • info

      added the new optional request property

    • info

      added the required property / to the response with the status