Messages, Mail and Texts API
Reading what an agent account received, and sending email and texts from it. The steps are in the Email and Phone number and texts guides.
Messages
- GET /v1/accounts/:id/messages?limit&cursor&channel - inbound and sent mail, SMS, voicemail, newest first. channel is email, sms, voicemail, call or post.
- GET /v1/accounts/:id/messages/:messageId - one message. Any agent of the customer reads any of its accounts messages under its own Passport, unless the owner set read_teammates to false for it; an agent of another customer gets 404. A read of another agent's message is recorded in the audit log without its content.
- GET /v1/accounts/:id/messages/:messageId/attachments/:fileId - a file the message carries, read through the message, with the drive's inline read answer. Only a file the message names.
- GET /v1/messages?agent_id&channel&sender&recipient&thread_id&after&before&q&limit&cursor - every message the caller may read, newest first, never the body. The window is the last 30 days; a q, sender, recipient or thread_id search needs a range of at most 90 days (400 otherwise) and may return fewer than limit with next_cursor set.
- GET|PUT /v1/message-access and GET|PUT /v1/agents/:agentId/message-access - what an agent reads and sends: { read_teammates?, messages_read_only? } (null follows the next scope). Reads return { agent_id, read_teammates, messages_read_only, effective, source }. read_teammates (default true) false limits the agent to its own account; messages_read_only (default false) true lets it read but refuses every send, reply, forward, text, Telegram message, letter and invite mail with 403 MESSAGES_READ_ONLY. Owner or admin only; an agent is refused.
- DELETE /v1/accounts/:id/messages/:messageId - owner or admin only. Deletes the message and the files received with it. Returns 204.
Every inbound message is signature-checked at the provider boundary, scanned for prompt injection and stored encrypted until you delete them; their stored bytes count in the drive's storage total (the first 25 GiB free, then at cost), and unpaid storage never deletes a message. With controls on, a flagged message comes back withheld with its security event instead of its content, unless the owner chose to have flagged content of that severity delivered with its flag; with controls off it is delivered with a flag naming the event. The owner or an admin sets, separately for warning and critical, withhold (the default) or deliver with PUT /v1/flagged-content/settings (read it with GET); it applies to everything scanned on its way to an agent (mail, texts, voicemail, page text, tool output, drive files, memory writes, what is heard on a call) while controls are on, with no approval. On a call STACK holds, a withheld sentence still reaches STACK's model and the stored transcript, and a critical one ends the call whatever the setting. The account's agent reads with its Passport under the account's Mission; any other agent gets 404.
The files that arrive with an email are kept with it. Each is saved to the receiving agent's drive, private to that agent, and counts toward the drive's storage like any file. It has no end of its own and goes when its message is deleted, including at the sender's request, unless you changed its end. To keep a file, copy it with POST /v1/drive/files/:id/copy; the copy is the customer's own file like any other; a received file's end changes like any file's (PATCH), and a file whose end you changed stays when its message is deleted. A received file is untrusted content, scanned with the message (a flagged attachment withholds the message when controls are on, and its files are then kept for the account's owner alone: no agent sees them) and recorded on the data trail like the message. A message takes at most 25 MB of files in all, the most the mail provider sends, and every attachment is kept, an empty one and a text file over 10 MB included (that one is kept without being scanned). The message lists them in content.attachments as { filename, content_type, size_bytes, file_id }; read a file with the drive routes. The drive takes a file of any type. One that is not kept is listed with no file_id and not_saved naming why: too_large (past what is left of the message's 25 MB), unavailable (the mail provider no longer has the file, or it could not be read or saved just then), drive_read_only (the drive is read-only because its storage was not paid for), waiting (STACK is still saving it and tries again until the message ends) and withheld (it was flagged after the message arrived, so it is kept for the owner alone). The email is stored whichever of these applies. content.thread_id is the thread a reply goes in. A message that arrived keeps at most 50 To and Cc recipients between them and 50 Bcc, and every attachment. An email the account sent keeps every recipient, has content.bcc and the file_id of each file it attached.
Sender tags
Every inbound item says what STACK could tell about who wrote it, worked out when it arrived with no model call. A message carries sender_tags (a list, or null when it was not assessed: an outbound message, a call transcript, or one from before tags existed) and, for a look-alike, sender_resembles. The same tags are on the wake-up the agent gets, on a call that came in, on a calendar invite, and, through from_message_id on add_memory, on every fact memory learns from the message. They compare the sender with everyone the customer's agents have dealt with, in either direction, across all of the customer's agents. Everyone an email went to counts as dealt with: every To, Cc and Bcc recipient, not only the first.
- new_sender - None of the customer's agents has dealt with this sender before: nothing was sent to them and nothing received from them.
- new_domain - The sender's company domain has not appeared in the customer's agents' mail before (free mail providers such as gmail.com are not counted).
- lookalike_domain - The sender's domain looks like one the customer's agents already know, named in `resembles`, but is not the same domain.
- name_matches_known_contact - The sender's name is the same as a known contact's, but the address or Telegram user is not the one that contact has used.
- payment_details - The message contains a bank account number or IBAN.
- organizer_not_sender - The calendar invite's organizer is not the person who sent it.
- unverified_sender - Nobody has checked who sent this post: the sender is only what the envelope says.
Mail gets the first five (and organizer_not_sender when it carries an invite), texts and voicemail get new_sender and payment_details, a call ringing on the account's number gets new_sender, Telegram gets new_sender and name_matches_known_contact, and post is always unverified_sender. Tags warn; they never block or hide a message, and a message with none may still be from someone pretending. A page the agent reads in its browser carries lookalike_domain when its site imitates a known domain, and the one-time card number can only be typed on the site the card was issued for.
Send mail and texts
curl -X POST https://api.getstack.run/v1/accounts/acct_123/email/send \
-H "Authorization: Bearer <access token>" -H "Content-Type: application/json" \
-d '{"to":"person@example.com","subject":"Order 1182","body":"Your order shipped."}'
curl -X POST https://api.getstack.run/v1/accounts/acct_123/email/send \
-H "Authorization: Bearer <access token>" -H "Content-Type: application/json" \
-d '{"to":["person@example.com","buyer@example.org"],"cc":["team@example.com"],"subject":"Order 1182","body":"Your order shipped. The invoice is attached.","attachments":[{"file_id":"drv_a1b2c3d4e5f6"}]}'
curl -X POST https://api.getstack.run/v1/accounts/acct_123/sms/send \
-H "Authorization: Bearer <access token>" -H "Content-Type: application/json" \
-d '{"to":"+14155550123","body":"Your order shipped."}'
- email: to (one address or a list; required, cc or bcc alone is refused), cc and bcc (lists of addresses), body and subject unless thread_id replies in an existing thread; body_html is optional. Answers 201 with message_id, thread_id, status, and to, cc and bcc as they were sent, and dropped when an address was left out (each as given, with not_an_address). The subject is one line: a line break returns 400.
- Recipients: OpenMail, the mail provider, takes one To address, so the first to address is the To and any further to addresses are delivered as Cc (the answer shows where each went). An address is used once, in the first place it is named, whatever its case. An email needs at least one To recipient: cc or bcc alone is refused. The account's own address may be a recipient like any other. Your controls are told every recipient (To, Cc and Bcc), exactly the people the email goes to, and decide the email as a whole.
- attachments: a list of files, each { file_id, filename? } or { filename, content_type, content_base64 }. A file_id attaches a file of the agent's drive (its own private files and the account's shared ones; the owner sees every file) as it is; filename renames it in this email only. Files sent inline come to at most 10 MB in all; attach a larger file by file_id. An inline file may be of any type, as in the drive, an empty one included. A file that is text is read by the data-flow rule whatever it is called.
- Limits are OpenMail's: attachments come to at most 25 MB in one email, the body is at most 100,000 characters, the HTML body 500,000 and the subject 998. OpenMail states no limit on the number of recipients or attachments, and STACK sets none. Over 25 MB returns 413 EMAIL_ATTACHMENTS_TOO_LARGE; an email OpenMail refuses returns 422 ACCOUNT_SEND_FAILED with the reason in words.
- POST /v1/accounts/:id/messages/:messageId/reply - { body, body_html?, reply_all?, cc?, bcc?, subject?, attachments?, include_quote? }. Answers an email the account received, in its thread: OpenMail sets In-Reply-To and References from the thread id, so the mail client keeps the conversation together, and the text quoted below the answer is the message being answered (include_quote is true unless you say false, which leaves the quote out). It goes to the person who wrote it (to every address its From names, when it names several); with reply_all it also goes to everyone else the original was sent to (read from the original's own To and Cc headers), never the account's own address. An entry of those headers that is not one plain address is left out and named in dropped. subject replaces the thread's subject.
- POST /v1/accounts/:id/messages/:messageId/forward - { to, cc?, bcc?, body?, include_quote?, include_attachments?, attachments? }. Sends a received email on as a new email, in no thread (the people it goes to never see the conversation it came from), with the subject "Fwd: ...", your own note in body above the original's headers and text (include_quote is true unless you say false, which leaves them out), and the files kept from the original attached (include_attachments is true unless you say false; attachments adds more files). A file that was not kept, or has since been deleted from the drive, is named in the text as "[Not attached: name (reason)]".
- A reply or forward names the received email by its message id (amsg_...). A message that is not an email, was not received by the account, or was withheld returns 422 EMAIL_MESSAGE_NOT_ANSWERABLE. Both take the same admission, one metered action, your controls (email.send), the data-flow rule and daily limit as any email.
- sms: to in E.164 form and body up to 1,600 characters.
- one_way (email send and sms, optional) is accepted and has no effect: STACK adds nothing to an email or a text.
- reply_to_message (email send, sms and calls, optional): the id (amsg_...) of the received message the send answers. A policy that sets the account's recipients.email, recipients.sms or recipients.call to "per_mission" requires it, and the send then goes only to whoever wrote that message (see Policies). A reply needs no field: the message in its path is the pin. A forward has no pin.
- Email sent from STACK's shared domain is limited to 20 a day for a customer's first 14 days and 100 a day after that (UTC); past it the API returns 429 SHARED_MAIL_DAILY_LIMIT. On STACK's shared mail domain the cap counts recipients, not emails: every To, Cc and Bcc address of every email a customer's agents send counts, and an email that would pass it is refused whole. Email from your own verified domain has no STACK daily limit. STACK sets no daily limit on texts, calls or post.
- An inbox OpenMail suspends is paused until OpenMail reactivates it. STACK pauses no phone for texts that bounce or that a carrier filters as spam; it records them. POST /v1/accounts/:id/pieces/resume with {"piece":"inbox"|"phone"} lifts a pause (operator only).
Consent
You must have the recipient's consent to be texted or called wherever the law requires it, such as under the TCPA in the United States. The time of day and calling hours rules for marketing texts and calls are yours to keep too, where the law sets them.
Where texts and calls can go
Texts and calls go to any country Twilio can reach from the account's number, charged at cost from Twilio's price to that destination (read from Twilio and kept for a day). STACK has no list of countries, no calling hours and no price ceiling of its own. It refuses a text or a call only when:
- the wallet or budget cannot cover the text, or the first 10 minutes of the call;
- the number is on your do-not-contact list (403 RECIPIENT_OPTED_OUT);
- your own rules refuse it: your decider, budgets and spending limits, only where you have set them;
- the account or its phone is paused or not set up (a US local number also needs carrier registration, and a toll-free number its verification);
- Twilio has no price for the destination, or does not allow it from the account's number, as with a premium-rate or high-risk number or a region its geographic permissions do not enable (422 DESTINATION_NOT_AVAILABLE).
If Twilio itself declines for want of funds on STACK's account, the API returns 503 PROVIDER_CAPACITY_UNAVAILABLE and nothing is charged.
Do-not-contact list
Each customer has one do-not-contact list. A number goes on it when it texts STOP (or another opt-out word) to the account's number or when the customer adds it, and a STOP is not a complaint: it does not count toward pausing the phone. Nothing a person says on a call adds a number. A text or a call to a listed number is refused with 403 RECIPIENT_OPTED_OUT, and nothing is sent or charged. A text to the account's number with START or UNSTOP takes the number off the list whole, texts and calls. The owner and admins read, add to and clear the list; an agent's credential may read it and add to it, and never clear it. No route is counted as an action:
- POST /v1/opt-outs (scope accounts:manage; owner, admins and the account's agent) - { number } in E.164 form adds a number to the list, texts and calls both. 201 with the entry, or 200 with the entry that was already there; an agent may add and never remove.
- GET /v1/opt-outs (scope accounts:manage; owner, admins and the account's agent) - { opt_outs: [...] }. Each has id (aoo_...), number in full (E.164), texts_blocked, calls_blocked, source (text_stop, customer or call_request) and created_at.
- DELETE /v1/opt-outs/:id (scope accounts:manage; owner and admins only) - { removed: boolean }. Texts and calls to that number go through again.
Blocked callers
Each customer also has one blocked-callers list. An incoming call from a number on it is turned away before it rings: it wakes no agent, takes no voicemail and costs nothing. The owner and admins read, add to and take numbers off the list; an agent's credential may read it and add to it, and never take a number off. No route is counted as an action:
- POST /v1/blocked-callers (scope accounts:manage; owner, admins and the account's agent) - { number } in E.164 form adds a number. 201 with the entry, or 200 with the entry that was already there; an agent may add and never remove.
- GET /v1/blocked-callers (scope accounts:manage; owner, admins and the account's agent) - { blocked_callers: [...] }. Each has id (abk_...), number in full (E.164) and created_at.
- DELETE /v1/blocked-callers/:id (scope accounts:manage; owner and admins only) - { removed: boolean }. Calls from that number ring again.
Toll-free verification
Texts from a toll-free number need an approved toll-free verification; until then a send returns 403 TOLL_FREE_VERIFICATION_REQUIRED. Receiving texts works without it. POST /v1/accounts/:id/phone/toll-free-verification submits the owner's business details to Twilio under the owner's own sub-account (owner or admin only): business name, website, type and registration, address, contact, notification email, use case, message sample, opt-in type and evidence URLs, message volume, privacy policy and terms URLs. STACK keeps only the verification id and status. A verification already in review or approved returns 409. GET /v1/accounts/:id/phone/toll-free-verification returns verification_id, status (PENDING_REVIEW, IN_REVIEW, TWILIO_APPROVED, TWILIO_REJECTED), rejection_reason and sending_allowed (operator only).
Adding a number, submitting a toll-free verification and lifting a pause are governance actions, like opening an account. A Console session passes. Any other credential gets 403 GOVERNANCE_APPROVAL_REQUIRED with details.approval_url and details.approval_id; a human approves at the link, then retry the same body with X-Governance-Approval: approval_id. Removing a number needs no approval.