The Emails API from OKKI Go (go.okki.ai) — 6 operations for batch and personalized cold-outreach email sending and per-mail delivery tracking.
openapi: 3.0.3
info:
title: OKKI Go Emails API
description: OKKI Go is a B2B prospecting engine for AI agents and sales teams from Xiaoman (小满科技, an Alibaba company). Search global B2B companies, unlock company profiles and decision-maker contact emails, send batch or personalized cold outreach email (EDM), and track delivery — designed to be driven from AI agents via the provider-published OKKI Go Agent Skill. This OpenAPI was generated by API Evangelist from the provider's published API reference shipped inside the @okki-global/okki-go npm package (skill/references/api-reference.md, v1.3.4); endpoint paths, parameters, billing notes, and error semantics are taken verbatim from that document. Errors use RFC 7807 Problem Details. All authenticated endpoints share a 60 requests/minute rate limit.
version: 1.0.0
x-generated: '2026-07-21'
x-method: generated
x-source: npm @okki-global/okki-go 1.3.4 skill/references/api-reference.md
servers:
- url: https://go.okki.ai
description: OKKI Go production
tags:
- name: Emails
paths:
/api/v1/emails/send/batch:
post:
operationId: sendBatchEmails
tags:
- Emails
summary: Send batch outreach email (one template, many recipients)
description: Costs 1 EDM quota per recipient; max 100 recipients per request. Asynchronous — record task_id to track progress. Insufficient balance refunds all and returns 402.
security:
- apiKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- content
- body_format
- recipients
properties:
content:
type: string
maxLength: 50000
description: Body template; variable names written bare (no braces)
body_format:
type: string
enum:
- text
- html
task_subject:
type: string
maxLength: 255
recipients:
type: array
minItems: 1
maxItems: 100
items:
type: object
required:
- email
- subject
properties:
email:
type: string
format: email
subject:
type: string
maxLength: 200
nickname:
type: string
variables:
type: object
additionalProperties:
type: string
responses:
'201':
description: Task created
content:
application/json:
schema:
type: object
properties:
task_id:
type: integer
total:
type: integer
status:
type: string
'402':
$ref: '#/components/responses/InsufficientCredits'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
'502':
$ref: '#/components/responses/UpstreamError'
/api/v1/emails/send/personalized:
post:
operationId: sendPersonalizedEmails
tags:
- Emails
summary: Send personalized outreach emails (independent bodies)
description: Costs 1 EDM quota per email; max 100 emails per request. Partial-balance failures refund deducted quota and return 402.
security:
- apiKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- emails
properties:
task_subject:
type: string
maxLength: 255
emails:
type: array
minItems: 1
maxItems: 100
items:
type: object
required:
- content
- body_format
- email
- subject
properties:
content:
type: string
maxLength: 50000
body_format:
type: string
enum:
- text
- html
email:
type: string
format: email
subject:
type: string
maxLength: 200
nickname:
type: string
variables:
type: object
additionalProperties:
type: string
responses:
'201':
description: Tasks created
content:
application/json:
schema:
type: object
properties:
total:
type: integer
tasks:
type: array
items:
type: object
properties:
task_id:
type: integer
mail_id:
type: integer
email:
type: string
'402':
$ref: '#/components/responses/InsufficientCredits'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
'502':
$ref: '#/components/responses/UpstreamError'
/api/v1/emails/tasks:
get:
operationId: listEmailTasks
tags:
- Emails
summary: List email tasks
description: Free. Filter by task ids, subject, status (pending/requested/completed/partial/failed), recipient, and creation window; paginated (page/page_size, 1-100) and sortable.
security:
- apiKey: []
parameters:
- name: task_ids
in: query
schema:
type: string
description: Comma-separated task ids
- name: subject
in: query
schema:
type: string
- name: task_subject
in: query
schema:
type: string
- name: statuses
in: query
schema:
type: string
description: Comma-separated pending/requested/completed/partial/failed
- name: recipient_email
in: query
schema:
type: string
- name: recipient_nickname
in: query
schema:
type: string
- name: created_from
in: query
schema:
type: string
format: date-time
- name: created_to
in: query
schema:
type: string
format: date-time
- name: page
in: query
schema:
type: integer
default: 1
- name: page_size
in: query
schema:
type: integer
default: 20
minimum: 1
maximum: 100
- name: sort_by
in: query
schema:
type: string
enum:
- created_at
- task_id
default: created_at
- name: sort_order
in: query
schema:
type: string
enum:
- asc
- desc
default: desc
responses:
'200':
description: Task list
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/EmailTask'
total:
type: integer
page:
type: integer
page_size:
type: integer
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
/api/v1/emails/tasks/{taskId}:
get:
operationId: getEmailTask
tags:
- Emails
summary: Get email task detail (per-mail delivery status)
description: Free. Includes per-mail status, callbackReceivedAt delivery confirmation, and failureReason. 404 when the task does not exist or belongs to another user.
security:
- apiKey: []
parameters:
- name: taskId
in: path
required: true
schema:
type: integer
responses:
'200':
description: Task detail with mails[]
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/EmailTask'
- type: object
properties:
content:
type: string
bodyFormat:
type: string
mails:
type: array
items:
$ref: '#/components/schemas/EmailMail'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
/api/v1/emails/mails:
get:
operationId: listEmailMails
tags:
- Emails
summary: List individual sent-mail records across tasks
description: Free. Filter by task/mail ids, subject, status (pending/requested/sent/failed), recipient, sent and callback windows; paginated and sortable.
security:
- apiKey: []
parameters:
- name: task_ids
in: query
schema:
type: string
- name: mail_ids
in: query
schema:
type: string
- name: subject
in: query
schema:
type: string
- name: statuses
in: query
schema:
type: string
description: Comma-separated pending/requested/sent/failed
- name: recipient_email
in: query
schema:
type: string
- name: recipient_nickname
in: query
schema:
type: string
- name: sent_from
in: query
schema:
type: string
format: date-time
- name: sent_to
in: query
schema:
type: string
format: date-time
- name: received_from
in: query
schema:
type: string
format: date-time
- name: received_to
in: query
schema:
type: string
format: date-time
- name: page
in: query
schema:
type: integer
default: 1
- name: page_size
in: query
schema:
type: integer
default: 20
minimum: 1
maximum: 100
- name: sort_by
in: query
schema:
type: string
enum:
- sent_at
- callback_received_at
- mail_id
- status
default: sent_at
- name: sort_order
in: query
schema:
type: string
enum:
- asc
- desc
default: desc
responses:
'200':
description: Mail records
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/EmailMail'
total:
type: integer
page:
type: integer
page_size:
type: integer
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
/api/v1/emails/mails/{mailId}:
get:
operationId: getEmailMail
tags:
- Emails
summary: Get a single sent mail (full body and delivery state)
description: Free. bodyFormat (text|html) governs rendering. 404 when the mail does not exist or belongs to another user.
security:
- apiKey: []
parameters:
- name: mailId
in: path
required: true
schema:
type: integer
responses:
'200':
description: Mail detail
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/EmailMail'
- type: object
properties:
content:
type: string
bodyFormat:
type: string
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
components:
schemas:
Problem:
type: object
description: RFC 7807 Problem Details error envelope.
properties:
type:
type: string
title:
type: string
status:
type: integer
detail:
type: string
instance:
type: string
code:
type: string
EmailMail:
type: object
properties:
mailId:
type: integer
taskId:
type: integer
recipientEmail:
type: string
recipientNickname:
type: string
subject:
type: string
status:
type: string
enum:
- pending
- requested
- sent
- failed
sentAt:
type: string
format: date-time
nullable: true
callbackReceivedAt:
type: string
format: date-time
nullable: true
failureReason:
type: string
nullable: true
EmailTask:
type: object
properties:
taskId:
type: integer
totalCount:
type: integer
status:
type: string
enum:
- pending
- requested
- completed
- partial
- failed
sentCount:
type: integer
failedCount:
type: integer
openedCount:
type: integer
taskSubject:
type: string
createdAt:
type: string
format: date-time
completedAt:
type: string
format: date-time
nullable: true
responses:
InsufficientCredits:
description: 'RFC 7807 insufficient-credits: search points or EDM quota exhausted'
content:
application/json:
schema:
$ref: '#/components/schemas/Problem'
Unauthorized:
description: 'RFC 7807 unauthorized: API key missing, invalid, or revoked'
content:
application/json:
schema:
$ref: '#/components/schemas/Problem'
NotFound:
description: 'RFC 7807 not-found: resource does not exist or belongs to another user'
content:
application/json:
schema:
$ref: '#/components/schemas/Problem'
Forbidden:
description: 'RFC 7807 forbidden: plan does not include EDM sending'
content:
application/json:
schema:
$ref: '#/components/schemas/Problem'
RateLimited:
description: 'RFC 7807 rate-limit / quota-exceeded: 60 requests/minute shared across authenticated endpoints'
content:
application/json:
schema:
$ref: '#/components/schemas/Problem'
UpstreamError:
description: 'RFC 7807 upstream-error: EDM third-party service failure; deducted quota is refunded'
content:
application/json:
schema:
$ref: '#/components/schemas/Problem'
securitySchemes:
apiKey:
type: apiKey
in: header
name: Authorization
description: 'Authorization: ApiKey sk-your-key-here — API keys issued at https://go.okki.ai after registration.'