Browse the docs

Limits and good practice

The API refuses what would harm your sender reputation or break the rules of WhatsApp and email. Knowing the rules saves you debugging time.

You may send offers and news only to people who agreed to receive them. EzReach keeps the record of when and how they agreed.

  • Every contact has a choice: subscribed (offers and updates), no offers (updates about things they booked only) or no messages (nothing at all). POST /contacts with subscribed: true says the person agreed. Only send it for people who did.
  • A marketing template to somebody on "no offers" is refused with CONTACT_UNSUBSCRIBED. Utility templates, such as an order update, still go. Somebody on "no messages" can only get a login-code template (CONTACT_NO_MESSAGES).
  • To subscribe somebody who opted out, send optInEvidence: one line that says how they asked to hear from you again. Without it the API answers 409 OPT_OUT_ON_RECORD. If they asked for no messages at all, only their own START undoes it.
  • Templates can be sent at any time. Text and media messages only go within 24 hours of the customer's last message (WINDOW_CLOSED otherwise).
  • When you report an event for somebody EzReach does not know yet, they start on "no offers": they get updates about their booking and no campaigns, unless you send optInEvidence.
  • A marketing email needs recorded consent for that address. Record it with POST /email/consent (or in the panel) with a line of evidence, 5 to 300 characters, about how the person agreed. Without it the send is refused with NO_CONSENT.
  • Unsubscribing always works and cannot be undone by accident. Somebody who left is only subscribed again if the new consent is dated after the day they left.
  • Somebody who marked your email as spam, whose address bounced for good, or who asked for erasure can never be subscribed again.
  • Email consent belongs to the email address and is separate from WhatsApp consent. These calls never change somebody's WhatsApp choice.
  • Every email carries your business name, your postal address and an unsubscribe link. Add your postal address under Email > Footer & tracking first, or sends are refused with NO_POSTAL_ADDRESS.

What "transactional" means

kind: "transactional" is for a message the person needs because of something they did with you: a receipt, an order or booking confirmation, a password reset, an account notice. It does not need marketing consent, and somebody who unsubscribed from your marketing still gets it.

A transactional email is still refused for an address that bounced for good, marked your email as spam, is on Amazon's list or yours, was erased, or belongs to a blocked contact.

Limits for each address

  • Transactional: at most 5 emails a day and 20 a week to the same address through the API. More gets 429 ADDRESS_LIMIT with Retry-After.
  • Marketing: the most marketing emails you allow for one address in 7 days, campaigns and the API together. You set it under Email > Footer & tracking. More gets 422 FREQUENCY_CAP.
  • Your workspace has a daily email limit that campaigns and the API share (429 EMAIL_DAILY_LIMIT). It frees up at midnight India time.
  • Each email costs your workspace's email price, taken from your wallet. With too little in the wallet you get 402 INSUFFICIENT_BALANCE and nothing is sent.

Habits that keep you out of trouble

  • Send an Idempotency-Key with every send. Why and how.
  • Never retry SEND_OUTCOME_UNKNOWN. The message may already be delivered. Check its status first.
  • Retry only when the error says it is safe: details.retryable: true, or 429 after Retry-After.
  • Use webhooks, not polling. Webhooks tell you about receipts, replies and opt-outs as they happen. When a person opts out, stop sending them offers from your own system too.
  • Sync in batches. POST /contacts/bulk takes up to 1,000 contacts in one request.
  • Give each key the fewest permissions it needs, one key for each system, and keep keys on your server. Permissions.
  • Treat the code as the contract. Messages are for people and can change. Errors.
  • Deleting a contact is permanent. DELETE /contacts/{phone} removes their conversations and notes. Messages you sent them stay only as a record without their content.