Email API

Send and receive email through connected accounts, manage aliases and signatures, and view threaded email conversations via the Warpflow API.

Overview

The Email API lets you send email through a connected Google or Microsoft account, manage email aliases and signatures, and view inbound/outbound email conversations alongside SMS and voice in a unified thread.

Email integration uses Nylas under the hood. You connect your email account via OAuth in the dashboard, and Warpflow handles sending, receiving, and thread tracking.

Connect an email account

Open the Signals dashboard
Navigate to Settings → Email
Click Connect Email Account
Choose Google or Microsoft
Authorize access in the OAuth flow (handled by Nylas — your credentials never touch Warpflow servers)
Once connected, inbound emails begin flowing into the Signals pipeline automatically

Current limits: One email connection per tenant.

Supported providers: Google Workspace, Gmail, Microsoft 365, Outlook (via Nylas).

Send email

POST /api/v1/tenants/{tenant_id}/email/send
Authorization: Bearer <api_key>
Content-Type: application/json

Request body

{
  "to": [{ "name": "Jane Doe", "email": "jane@example.com" }],
  "subject": "Following up on your inquiry",
  "body": "Hi Jane,\n\nThanks for reaching out about dental implants...",
  "cc": [{ "email": "office@example.com" }],
  "bcc": [],
  "from": "support@yourdomain.com",
  "reply_to_message_id": "nylas-message-id-for-threading"
}

Field reference

Field	Required	Description
`to`	Yes	Array of recipients. Each needs at least `email`; `name` is optional
`subject`	Yes	Email subject line
`body`	Yes	Email body (plain text or HTML)
`cc`	No	Carbon copy recipients
`bcc`	No	Blind carbon copy recipients
`from`	No	Sender address. Must match the connected account email or a configured alias. Defaults to the connected account email
`reply_to_message_id`	No	Nylas message ID to reply to. Maintains email threading. Get this from the conversation history

Response (200)

{
  "success": true,
  "message_id": "nylas-msg-abc123",
  "thread_id": "nylas-thread-xyz789"
}

Rate limit

50 emails per hour per tenant.

Email signatures

The connected account's signature (configured in the dashboard) is automatically appended to every outgoing email. HTML-aware — the signature is inserted before the closing </body> tag if the body is HTML, or appended at the end for plain text.

Manage aliases

Aliases let you send and receive email from multiple addresses on the same domain (e.g., support@, billing@, hello@).

List aliases

curl -H "Authorization: Bearer wf_acme_abc123" \
  https://api.warpflow.ai/api/v1/tenants/acme/email/aliases

Response (200):

{
  "grant_email": "team@yourdomain.com",
  "aliases": ["support@yourdomain.com", "billing@yourdomain.com"]
}

Update aliases

curl -X PATCH \
  https://api.warpflow.ai/api/v1/tenants/acme/email/aliases \
  -H "Authorization: Bearer wf_acme_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "aliases": ["support@yourdomain.com", "billing@yourdomain.com", "hello@yourdomain.com"]
  }'

Response (200):

{
  "grant_email": "team@yourdomain.com",
  "aliases": ["support@yourdomain.com", "billing@yourdomain.com", "hello@yourdomain.com"]
}

Limits: Max 20 aliases per connection.

Auto-discovery: When an inbound email arrives at an address on your domain that isn't in your alias list, Warpflow automatically adds it. You can remove unwanted aliases via the PATCH endpoint.

Update email signature

curl -X PATCH \
  https://api.warpflow.ai/api/v1/tenants/acme/email/signature \
  -H "Authorization: Bearer wf_acme_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "signature": "<p>Best regards,<br>The Acme Team</p><p><a href='\''https://acme.com'\''>acme.com</a></p>"
  }'

Response (200):

{
  "success": true,
  "signature": "<p>Best regards,<br>The Acme Team</p><p><a href='https://acme.com'>acme.com</a></p>"
}

Max 4,096 characters. Supports HTML.

View email conversations

Email messages appear in the same conversation timeline as SMS and voice, grouped by contact.

List conversations with email filter

curl -H "Authorization: Bearer wf_acme_abc123" \
  "https://api.warpflow.ai/api/v1/tenants/acme/conversations?alias=support@yourdomain.com"

The alias query parameter filters conversations to only those received at a specific email address.

Response (200):

{
  "conversations": [
    {
      "contact_id": "contact_abc123",
      "contact_name": "Jane Doe",
      "contact_email": "jane@example.com",
      "last_message": "Do you accept Delta Dental insurance?",
      "last_channel": "email",
      "last_timestamp": "2026-02-22T14:30:00Z",
      "lead_id": "lead_xyz789",
      "lead_state": "open",
      "score_tier": "warm"
    }
  ],
  "cursor": "eyJjb250YWN0X2lkIjoiY29udGFjdF9hYmMxMjMifQ",
  "has_more": false
}

Conversation detail

curl -H "Authorization: Bearer wf_acme_abc123" \
  https://api.warpflow.ai/api/v1/tenants/acme/conversations/contact_abc123

Response (200):

{
  "contact_id": "contact_abc123",
  "contact_name": "Jane Doe",
  "messages": [
    {
      "channel": "email",
      "body": "Plain text version of the email",
      "html_body": "<div>Sanitized HTML content</div>",
      "subject": "Re: Your inquiry about dental implants",
      "thread_id": "nylas-thread-xyz789",
      "message_id": "nylas-msg-abc123",
      "received_alias": "support@yourdomain.com",
      "to": ["support@yourdomain.com"],
      "cc": ["office@yourdomain.com"],
      "actor": "contact",
      "timestamp": "2026-02-22T14:30:00Z"
    },
    {
      "channel": "sms",
      "body": "Hi, just following up on my email about dental implants",
      "actor": "contact",
      "timestamp": "2026-02-22T15:45:00Z"
    }
  ]
}

The response includes messages from all channels (email, SMS, voice) in chronological order, giving you the full cross-channel conversation.

Use the message_id value as reply_to_message_id when sending a reply to maintain email threading.

Send message via conversation API

You can also send email through the conversations endpoint (the same one used for SMS):

curl -X POST \
  https://api.warpflow.ai/api/v1/tenants/acme/conversations/contact_abc123/messages \
  -H "Authorization: Bearer wf_acme_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Thanks for your message, we'\''ll get back to you shortly.",
    "channel": "email"
  }'

Response (200):

{
  "success": true,
  "message_id": "nylas-msg-def456",
  "thread_id": "nylas-thread-xyz789",
  "channel": "email"
}

This finds the most recent email lead for the contact and sends through the connected Nylas grant. To send SMS instead, set "channel": "sms".

How inbound email works

When someone sends an email to your connected account (or any configured alias):

Nylas delivers the event via webhook to Warpflow
Warpflow resolves the sender to a contact (or creates one)
The email is matched to an existing conversation thread or creates a new lead
The full Signals pipeline runs: classify → score → route → execute actions
The message appears in the dashboard work queue and conversation history

Thread tracking: Replies on the same email thread are grouped into the same lead. Warpflow uses Nylas thread IDs and RFC 5322 In-Reply-To / References headers for reliable thread matching, even when email providers reassign thread IDs.

Deduplication: Inbound emails are deduplicated by RFC 5322 Message-ID, Nylas message ID, and content hash to prevent duplicate processing.

HIPAA restriction

Email endpoints return 403 HIPAA_RESTRICTED for HIPAA-enabled tenants. The Nylas standard plan does not include a Business Associate Agreement (BAA), which is required for processing Protected Health Information (PHI) via email. Healthcare tenants needing HIPAA-compliant email should contact support.

Next steps

Authentication — set up API keys
Webhooks — send events from other platforms
Integration Recipes — common email automation patterns

On this page