# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand. overlay: 1.0.0 info: title: API Evangelist conversational phrasing for Twilio SendGrid Marketing Campaigns Contacts API version: 1.0.0 extends: openapi/sendgrid-contacts-api-openapi.yml actions: - target: $.info update: x-apievangelist-phrasing: method: generated generated: '2026-09-24' generator: build-phrasing.py label: Generated by API Evangelist operations: 15 - target: $.paths['/v3/marketing/contacts'].get update: x-apievangelist-phrasing: intent: Preview a sample of recent contacts effect: read questions: - Can I get a quick look at the 50 most recently added marketing contacts in SendGrid? - What does the sample contacts view return besides the contacts themselves? instructions: - text: Show me a sample of my most recently uploaded marketing contacts. - text: Pull the recent-contacts sample sorted by email address. method: generated generated: '2026-09-24' - target: $.paths['/v3/marketing/contacts'].put update: x-apievangelist-phrasing: intent: Add or update marketing contacts effect: write questions: - How do I add new contacts or update existing ones in Marketing Campaigns? - How many contacts can I upsert in a single request? - Can I put contacts onto specific lists at the same time I upsert them? instructions: - text: 'Upsert these contacts: {contacts}.' slots: contacts: requestBody.contacts - text: Add or update {contacts} and attach them to lists {list_ids}. slots: contacts: requestBody.contacts list_ids: requestBody.list_ids method: generated generated: '2026-09-24' - target: $.paths['/v3/marketing/contacts'].delete update: x-apievangelist-phrasing: intent: Delete marketing contacts effect: destructive questions: - How can I delete several marketing contacts at once by their IDs? - Is it possible to wipe every contact in my account in one call? instructions: - text: Delete the contacts with IDs {ids}. slots: ids: query.ids - text: Delete all of my marketing contacts, setting delete_all_contacts to {delete_all_contacts}. slots: delete_all_contacts: query.delete_all_contacts method: generated generated: '2026-09-24' - target: $.paths['/v3/marketing/contacts/{id}'].get update: x-apievangelist-phrasing: intent: Get one contact's full details effect: read questions: - What fields and custom data are stored on a single contact when I look it up by ID? - Where do I see every field for one specific contact? instructions: - text: Get the full record for contact {id}. slots: id: path.id - text: Show all fields stored on contact ID {id}. slots: id: path.id method: generated generated: '2026-09-24' - target: $.paths['/v3/marketing/contacts/batch'].post update: x-apievangelist-phrasing: intent: Fetch many contacts by their IDs at once effect: read questions: - Can I fetch up to 100 contacts in one call if I already have their IDs? - Is there a faster way than looking up contacts by ID one at a time? instructions: - text: Fetch the batch of contacts with IDs {ids} in one request. slots: ids: requestBody.ids - text: 'Retrieve these contact IDs together: {ids}.' slots: ids: requestBody.ids method: generated generated: '2026-09-24' - target: $.paths['/v3/marketing/contacts/{contact_id}/identifiers'].delete update: x-apievangelist-phrasing: intent: Remove one identifier from a contact effect: destructive questions: - Can I remove just a phone number or external ID from a contact without deleting the contact? - What happens if I try to remove a contact's only identifier? instructions: - text: Remove the {identifier_type} identifier {identifier_value} from contact {contact_id}. slots: identifier_type: requestBody.identifier_type identifier_value: requestBody.identifier_value contact_id: path.contact_id - text: Strip identifier {identifier_value} off contact {contact_id} but keep the contact. slots: identifier_value: requestBody.identifier_value contact_id: path.contact_id method: generated generated: '2026-09-24' - target: $.paths['/v3/marketing/contacts/count'].get update: x-apievangelist-phrasing: intent: Count all stored contacts effect: read questions: - How many marketing contacts do I have stored in total? - What is my current total contact count? instructions: - text: Tell me the total number of contacts in my account. - text: Get my overall marketing contact count. method: generated generated: '2026-09-24' - target: $.paths['/v3/marketing/contacts/exports'].get update: x-apievangelist-phrasing: intent: List contact export jobs effect: read questions: - Which contact exports are currently running or recently finished? - Where can I see the export type and status of all my contact export jobs? instructions: - text: List all of my contact export jobs. - text: Show every in-flight or recently completed contact export. method: generated generated: '2026-09-24' - target: $.paths['/v3/marketing/contacts/exports'].post update: x-apievangelist-phrasing: intent: Export contacts from lists or segments effect: write questions: - How do I export the contacts in a list or segment to a file? - Can I get an email with the download link when my contact export is ready? - Is there a maximum file size I can set for a contact export? instructions: - text: Export the contacts in lists {list_ids} as {file_type}. slots: list_ids: requestBody.list_ids file_type: requestBody.file_type - text: Start a contact export for segments {segment_ids} and email me when it finishes via {notifications}. slots: segment_ids: requestBody.segment_ids notifications: requestBody.notifications method: generated generated: '2026-09-24' - target: $.paths['/v3/marketing/contacts/exports/{id}'].get update: x-apievangelist-phrasing: intent: Check a contact export's status effect: read questions: - Is my contact export finished, and where are the download URLs? - What status does a specific contact export job have right now? instructions: - text: Check the status of contact export {id}. slots: id: path.id - text: Get the download links for finished contact export {id}. slots: id: path.id method: generated generated: '2026-09-24' - target: $.paths['/v3/marketing/contacts/imports'].put update: x-apievangelist-phrasing: intent: Import contacts from a CSV file effect: write questions: - Can I bulk import up to a million contacts from a CSV? - How do I map my CSV columns to contact fields during an import? instructions: - text: Start a {file_type} contact import using field mappings {field_mappings}. slots: file_type: requestBody.file_type field_mappings: requestBody.field_mappings - text: Import a CSV of contacts into lists {list_ids} with mappings {field_mappings}. slots: list_ids: requestBody.list_ids field_mappings: requestBody.field_mappings method: generated generated: '2026-09-24' - target: $.paths['/v3/marketing/contacts/imports/{id}'].get update: x-apievangelist-phrasing: intent: Check a contact import job's status effect: read questions: - Did my contact import or upsert job finish, and were there any errors? - Where do I check progress on a contact job using its job_id? instructions: - text: Check the status of contact import job {id}. slots: id: path.id - text: Show the results and errors for contact job {id}. slots: id: path.id method: generated generated: '2026-09-24' - target: $.paths['/v3/marketing/contacts/search'].post update: x-apievangelist-phrasing: intent: Search contacts with an SGQL query effect: read questions: - Can I search my contacts with a query language instead of exact matches? - Why does searching contacts by email need the address in lower case? instructions: - text: Search my contacts with the SGQL query {query}. slots: query: requestBody.query - text: 'Find contacts matching this SGQL filter: {query}.' slots: query: requestBody.query method: generated generated: '2026-09-24' - target: $.paths['/v3/marketing/contacts/search/emails'].post update: x-apievangelist-phrasing: intent: Look up contacts by email address effect: read questions: - Can I find contacts by their email addresses, including alternate emails? - What is the limit on how many email addresses I can look up at once? instructions: - text: Look up the contacts with emails {emails}. slots: emails: requestBody.emails - text: Find the contact whose email address is {emails}. slots: emails: requestBody.emails method: generated generated: '2026-09-24' - target: $.paths['/v3/marketing/contacts/search/identifiers/{identifier_type}'].post update: x-apievangelist-phrasing: intent: Look up contacts by an identifier type effect: read questions: - Which identifier types can I use to find contacts, like phone number ID or external ID? - Can I look up contacts by their anonymous ID? instructions: - text: Find contacts whose {identifier_type} matches {identifiers}. slots: identifier_type: path.identifier_type identifiers: requestBody.identifiers - text: Look up contacts by {identifier_type} values {identifiers}. slots: identifier_type: path.identifier_type identifiers: requestBody.identifiers method: generated generated: '2026-09-24'