diff --git a/source/includes/rest/_broadcasts.md b/source/includes/rest/_broadcasts.md index 030220eb6c9..20c40e43580 100644 --- a/source/includes/rest/_broadcasts.md +++ b/source/includes/rest/_broadcasts.md @@ -56,7 +56,10 @@ with [Set the audience](#set-the-audience). "status": "sent", "name": "4 Marketing Automation Trends for 2015", "from_name": "John Doe", - "from_email": "john@example.com", + "from_email": "john@acme.com", + "from_email_address_id": "1234567", + "reply_to": "support@acme.com", + "reply_to_email_address_id": "1234569", "postal_address": "123 Anywhere St\nFresno, CA 99999", "localize_sending_time": true, "send_at": "2015-07-01T10:00:00Z", @@ -111,7 +114,19 @@ with [Set the audience](#set-the-audience). from_email - A "from email" that appears in your sent emails and can be changed on a per email basis. This setting overrides the account's default from email. + The address the Single-Email Campaign is sent from: its own From address, or the account's default From address if it has none. Read-only; set it with from_email_address_id. + + + from_email_address_id + The id of the address in from_email, matching an id in the account's sending addresses. Returns null if the account has no default From address, or if the address has been deleted; from_email still shows it. See Sender. + + + reply_to + The Reply-To address, or null when replies go to the From address. Read-only; set it with reply_to_email_address_id. + + + reply_to_email_address_id + The id of the address in reply_to, matching an id in the account's sending addresses, or null. It is also null if the Reply-To address has been deleted; reply_to still shows it. See Sender. postal_address @@ -127,7 +142,7 @@ with [Set the audience](#set-the-audience). bcc - A list of emails designated to receive a blind copy of the Single-Email Campaign. + A list of emails designated to receive a blind copy of the Single-Email Campaign. Read-only. created_at @@ -227,6 +242,109 @@ with a `422 Unprocessable Entity`: } ``` +## Sender + +> To change who a draft Single-Email Campaign is from and where replies go: + +```shell +curl -X PATCH "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/broadcasts/BROADCAST_ID" \ + -H "Content-Type: application/json" \ + -H 'User-Agent: Your App Name (www.yourapp.com)' \ + -u YOUR_API_KEY: \ + -d @- << EOF + { + "broadcasts": [{ + "from_name": "Acme Support", + "from_email_address_id": "1234568", + "reply_to_email_address_id": "1234569" + }] + } +EOF +``` + +```ruby +require "net/http" +require "json" + +uri = URI("https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/broadcasts/BROADCAST_ID") + +request = Net::HTTP::Patch.new(uri) +request.basic_auth("YOUR_API_KEY", "") +request["User-Agent"] = "Your App Name (www.yourapp.com)" +request["Content-Type"] = "application/json" +request.body = { + broadcasts: [{ + from_name: "Acme Support", + from_email_address_id: "1234568", + reply_to_email_address_id: "1234569" + }] +}.to_json + +response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http| + http.request(request) +end + +puts response.body +``` + +```javascript +const response = await fetch( + "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/broadcasts/BROADCAST_ID", + { + method: "PATCH", + headers: { + "Content-Type": "application/json", + "User-Agent": "Your App Name (www.yourapp.com)", + "Authorization": "Basic " + Buffer.from("YOUR_API_KEY:").toString("base64") + }, + body: JSON.stringify({ + broadcasts: [{ + from_name: "Acme Support", + from_email_address_id: "1234568", + reply_to_email_address_id: "1234569" + }] + }) + } +); + +const body = await response.json(); +``` + +> If an address cannot be used, responds with a 422 Unprocessable Entity and changes nothing: + +```json +{ + "errors": [{ + "code": "validation_error", + "attribute": "from_email_address_id", + "message": "hello@example.com is not verified: use the id of an address in the account's sending_addresses that has verified: true." + }] +} +``` + +A Single-Email Campaign's From name, From address and Reply-To address can be set when you +[create](#create-a-single-email-campaign) it, and changed while it is a `draft` with +[Update a Single-Email Campaign](#update-a-single-email-campaign). + +* `from_name` is free text, up to 255 characters. It cannot be blank, and supports Liquid + templating. +* The From and Reply-To addresses are chosen by id, never typed in. Use an `id` from the + account's [sending addresses](#sending-addresses), returned by + [Fetch an account](#fetch-an-account). +* `from_email_address_id` must be an address with `verified: true`. +* `reply_to_email_address_id` must be an address with `verified: true` and + `auto_generated: false`. +* On update, send `null` or `""` to clear either one. A cleared From address sends from the + account's default From address, and a cleared Reply-To sends replies to the From address. + +Any other id, such as an unverified or deleted address, or one that belongs to another account, +responds with a `422 Unprocessable Entity` and changes nothing. + +`from_email`, `reply_to` and `bcc` are read-only: they are returned in responses and ignored if +sent. + +A sender set here appears in the Drip app, the same as one chosen there. + ## List all Single-Email Campaigns > To list Single-Email Campaigns in an account: @@ -485,6 +603,18 @@ everyone eligible to receive them. [Set the audience](#set-the-audience) to narr postal_address Optional. A physical mailing address for CAN-SPAM compliance. Defaults to the account's postal address. + + from_name + Optional. The name the email is sent from (255 characters maximum). Supports Liquid templating. Defaults to the account's default From name. + + + from_email_address_id + Optional. The id of a verified address in the account's sending addresses to send from. Defaults to the account's default From address. See Sender. + + + reply_to_email_address_id + Optional. The id of a verified, non-auto-generated address in the account's sending addresses to receive replies. If omitted, replies go to the From address. See Sender. + @@ -652,7 +782,8 @@ const body = await response.json(); ``` Only Single-Email Campaigns in the `draft` status can be updated via the API; all other -statuses are read-only. Updates are partial: only the fields you include are changed. +statuses are read-only. Updates are partial: only the fields you include are changed. To change +the From name, From address or Reply-To address, see [Sender](#sender). Status, scheduling, and the audience are not updated here. Each has its own endpoint: [Set the audience](#set-the-audience), [Schedule](#schedule-a-single-email-campaign), and @@ -692,6 +823,18 @@ Status, scheduling, and the audience are not updated here. Each has its own endp postal_address Optional. A physical mailing address for CAN-SPAM compliance. + + from_name + Optional. The name the email is sent from (255 characters maximum). Supports Liquid templating. + + + from_email_address_id + Optional. The id of a verified address in the account's sending addresses to send from. Send null or "" to use the account's default From address. See Sender. + + + reply_to_email_address_id + Optional. The id of a verified, non-auto-generated address in the account's sending addresses to receive replies. Send null or "" to have replies go to the From address. See Sender. +