---
title: "Create sender"
method: POST
path: "/v1/senders"
---

# Create sender

`POST /v1/senders`

## Request body

- SenderCreateRequest — Create a sender. Provide `phoneNumber` for an SMS/WhatsApp sender, `emailAddress` (with a verified email domain) for an email sender, or `enableSmsOneway: true` for a zero-setup one-way SMS sender — at least one is required.
  - `name` string, required
  - `phoneNumber` string — 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, or one already attached to another sender, returns 400 rather than creating a sender that cannot send. Omit for an email-only sender.
  - `enableVoice` boolean — 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.
  - `enableSmsOneway` boolean — Enable the one-way SMS channel (`sms_oneway`). Needs nothing else — no phone number, no credential — so it is the fastest way to get a sender that can send. Recipients cannot reply. Confirm with `sms_oneway` in the `channels` array on the response.
  - `setAsDefault` boolean
  - `webhookUrl` string, uri — HTTPS URL for webhook events.
  - `webhookEvents` WebhookEvent[] — Events to subscribe to.
  - `emailAddress` string, 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.
  - `emailDomainId` string — ID of the verified email domain to attach. Optional — resolved from `emailAddress`'s domain when omitted.
  - `emailFromName` string — Display name shown in the recipient's inbox for the email channel.
  - `emailReceivingEnabled` boolean — Enable inbound email receiving on this sender. Requires a verified MX record on the domain; ignored otherwise.

## Response `201`

Sender created.

- Sender
  - `id` string, required
  - `name` string, required
  - `phoneNumber` string, required — Phone number in E.164 format.
  - `channels` string[] — Channels this sender can actually send on right now, computed from its configuration. Empty means the sender cannot send or receive anything yet: a phoneNumber alone does not enable SMS or voice. Check this rather than inferring capability from phoneNumber or emailAddress.
  - `isDefault` boolean — Whether this sender is the project's default.
  - `webhook` SenderWebhook — Webhook configuration for the sender.
    - `url` string, uri, required — HTTPS URL that will receive webhook events.
    - `events` WebhookEvent[], required — List of events the webhook is subscribed to.
    - `secret` string — Webhook secret for signature verification. Only returned on create or regenerate.
    - `active` boolean, required — Whether the webhook is active.
  - `whatsapp` object — WhatsApp Business Account information. Only present if a WABA is connected.
    - `phoneNumberId` string — WhatsApp phone number ID from Meta.
    - `displayPhoneNumber` string — Display phone number.
    - `paymentStatus` object — Payment configuration status from Meta.
      - `setupStatus` string — Payment setup status (COMPLETE, NOT_STARTED, etc.).
      - `methodStatus` string — Payment method status (VALID, NONE, etc.).
      - `canSendTemplates` boolean — Whether template messages can be sent. Requires setupStatus=COMPLETE and methodStatus=VALID.
  - `emailAddress` string — From-address for the email channel, if configured.
  - `emailReceivingEnabled` boolean — Whether inbound email receiving is enabled for this sender.
  - `emailCatchAllEnabled` boolean — 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.
  - `createdAt` string, date-time
  - `updatedAt` string, date-time

## Other responses

- `400` — Invalid sender.
- `401` — Unauthorized.

---

[API](https://skmtc.net/zavudev/apis/zavu-unified-messaging-layer-api.md) · [All operations](https://skmtc.net/zavudev/apis/zavu-unified-messaging-layer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zavudev/zavu-unified-messaging-layer-api/revisions/07b87b6ae707/schema)