> ## Documentation Index > Fetch the complete documentation index at: https://docs.seamless.ai/llms.txt > Use this file to discover all available pages before exploring further. # Send bulk email > Queues email to saved contacts matching `filters`. `filters` must include at least one of `lists`, `contactIds`, `campaignIds`, or a text query. The audience is resolved before anything is queued. More than 500 matched contacts is a 400 — the send is not truncated. Opted-out and unsubscribed contacts are skipped. Does not consume public API credits. Repeat a request with the same `Idempotency-Key` header (or `idempotencyKey` body field) and the same body to replay the original job. Reusing a key with a different audience or message is a 422. ## OpenAPI ````yaml https://gist.githubusercontent.com/JustinAlia/6ff38a671f5f79895444b77c57f3afff/raw/v2-openapi.json post /emails/send-bulk openapi: 3.0.0 info: title: Seamless API description: >- [Privacy Policy](https://seamless.ai/policies/privacy-policy) In order to dramatically improve our offerings to customers, Seamless will be introducing a Public API which can be used to search Companies & Contacts, Enrich Lists, and offer integrations as an Endpoint for our customers. The API is build using [RESTful](https://en.wikipedia.org/wiki/REST) principles and is secured using OAuth 2.0 with the implicit grant flow. # Authentication ## API Key ### 1. **Register Your Application** To use the Seamless API, you need to register your application to obtain an API key. To create a new API key, go to [Seamless.AI | Settings](https://login.seamless.ai/settings/public-api) > API Key and click the *Create New Connection* button. Note: The Public API Connections menu will only appear if your account has access to the Public API. ### 2. **Use the Access Token** For all authenticated API requests, include the API key in the header: ``` Token: API_KEY ``` ## OAuth 2.0 ### 1. **Register Your Application** Before integrating, you have to setup your client credentials. To create a new API client, go to [Seamless.AI | Settings](https://login.seamless.ai/settings/public-api) > OAuth Connections, and click the *Create New Connection* button. Note: The Public API Connections menu will only appear if your account has access to the Public API. - `client_id` - `client_secret` - `redirect_uri` You’ll use these to authenticate and obtain tokens. --- ### 2. **Obtain Authorization Code** Redirect the user to Seamless.AI's OAuth authorization endpoint: ``` GET https://login.seamless.ai/oauth/authorize ``` ### Query Parameters: | Name | Description | | --- | --- | | `client_id` | Your client ID | | `redirect_uri` | The URL users are redirected to | | `state` | (Optional) CSRF protection string | **Example URL**: ``` GET https://login.seamless.ai/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback ``` Once the user authenticates, they will be redirected to your `redirect_uri` with a `code` parameter. If your `redirect_uri` contains any query parameters (such as `?foo=bar`), you must URL encode your `redirect_uri` for this step. --- ### 3. **Exchange Code for Access Token** ``` POST https://api.seamless.ai/api/client/v2/oauth/accessToken ``` ### Request Body (JSON): ```json { "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "redirect_uri": "https://yourapp.com/callback", "grant_type": "authorization_code", "code": "AUTHORIZATION_CODE_FROM_STEP_2" } ``` ### Response: ```json { "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_in": 10800, "expires_at": "2026-06-25T12:00:00.000Z", "refresh_token_expires_in": 604800, "refresh_token_expires_at": "2026-07-02T12:00:00.000Z" } ``` Access tokens expire after **180 minutes** by default. Integrations must use the `refresh_token` grant before expiry to obtain a new token pair. Existing long-lived tokens issued before this change remain valid until their original expiry. --- ### 4. **Use the Access Token** For all authenticated API requests, include the token in the header: ``` Authorization: Bearer ACCESS_TOKEN ``` --- ### 5. **Refreshing the Token** To refresh the access token: ``` POST https://api.seamless.ai/api/client/v2/oauth/accessToken ``` ### Request Body: ```json { "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "redirect_uri": "https://yourapp.com/callback", "grant_type": "refresh_token", "refresh_token": "YOUR_REFRESH_TOKEN" } ``` ### Response: ```json { "token_type": "Bearer", "access_token": "NEW_ACCESS_TOKEN", "refresh_token": "NEW_REFRESH_TOKEN", "expires_in": 10800, "expires_at": "2026-06-25T12:00:00.000Z", "refresh_token_expires_in": 604800, "refresh_token_expires_at": "2026-07-02T12:00:00.000Z" } ``` Each refresh rotates both the access and refresh tokens. Store the new `refresh_token` from every response. # Rate Limiting Rate limits are enforced at the **organization** level. All API usage for your Seamless organization counts against the same quota for each endpoint—limits are not applied separately per API key or per user. The default limit is **60 requests per minute** per endpoint. If you exceed the limit, the API responds with **429 Too Many Requests** and a JSON error body. Some endpoints may use different limits (for example, OAuth routes). Your organization may also have custom limits. The `X-RateLimit-Limit` header on each response always reflects the maximum number of requests allowed for that endpoint in the current rate limit window. Rate limit and remaining credits information will be returned in the response header of each request. The parameters are: | Name | Example | Description | | --- | --- | --- | | `X-RateLimit-Limit` | 60 | The maximum number of requests you're permitted to make in the current rate limit window for this endpoint. | | `X-RateLimit-Remaining` | 42 | The number of requests remaining in the current rate limit window. | | `X-RateLimit-Reset` | 1745587198 | The time at which the current rate limit window resets in epoch seconds. | | `X-PublicAPI-Credits` | 1000 | The number of credits remaining that can be used in requests. | version: 1.0.0 x-logo: url: https://s3.amazonaws.com/seamless.ai-public/logos/logo-full-dark.svg altText: Seamless logo href: https://login.seamless.ai termsOfService: https://seamless.ai/policies/terms-of-use servers: - url: https://api.seamless.ai/api/client/v2 description: Seamless API security: - OAuth2: [] - ApiKeyAuth: [] tags: - name: OAuth description: >- Exchange client credentials for an access token and inspect the authenticated caller. - name: Contact Search description: >- Search the Seamless.AI contact database. Searching does not consume credits; researching a result does. - name: Company Search description: >- Search the Seamless.AI company database. Searching does not consume credits; researching a result does. - name: Contact Research description: >- Resolve a contact's emails and phone numbers. Research is asynchronous: submit a request, then poll for results or receive them by webhook. - name: Company Research description: >- Resolve company firmographics and contact details. Research is asynchronous: submit a request, then poll for results or receive them by webhook. - name: Org Contacts description: >- Read and update the contacts already saved to your organization. These are the records research writes to, and the IDs other endpoints expect. - name: Org Companies description: Read and update the companies already saved to your organization. - name: Campaigns description: >- Create and run multi-step outbound campaigns, manage their steps, and enroll or remove contacts. - name: Emails description: Compose, preview, send, and track emails, individually or in bulk. - name: Tasks description: Read and act on the tasks a campaign generates for its assigned user. - name: Lists description: Group saved contacts and companies into named lists. - name: Templates description: Reusable email templates available to campaigns and one-off sends. - name: Saved Searches description: Persist search filters so a search can be re-run or shared later. - name: Calls description: >- Log call outcomes against saved contacts, and read the disposition and sentiment vocabularies. - name: Activity description: A chronological feed of engagement activity across your organization. - name: Credits description: Remaining research credits for the authenticated organization. - name: Features description: Feature access flags for the authenticated organization. - name: Reference description: >- Static lookup data — locations, statuses, and other vocabularies other endpoints accept. paths: /emails/send-bulk: post: tags: - Emails summary: Send bulk email description: | Queues email to saved contacts matching `filters`. `filters` must include at least one of `lists`, `contactIds`, `campaignIds`, or a text query. The audience is resolved before anything is queued. More than 500 matched contacts is a 400 — the send is not truncated. Opted-out and unsubscribed contacts are skipped. Does not consume public API credits. Repeat a request with the same `Idempotency-Key` header (or `idempotencyKey` body field) and the same body to replay the original job. Reusing a key with a different audience or message is a 422. operationId: sendBulkEmail parameters: - name: Idempotency-Key in: header required: false description: >- Retry token. Same key plus the same body replays the original job. Same key plus a different body is a 422. schema: type: string maxLength: 255 requestBody: required: true content: application/json: schema: type: object required: - from - filters properties: from: type: string description: Connected sender address. subject: type: string description: Required when `templateId` is omitted. body: type: string description: Required when `templateId` is omitted. templateId: type: integer scheduleAt: type: string format: date-time idempotencyKey: type: string maxLength: 255 filters: type: object additionalProperties: false description: | Saved-contact filters. Unknown keys are rejected. Must include at least one of `lists`, `contactIds`, `campaignIds`, or a text query. properties: contactIds: type: array maxItems: 500 items: type: integer lists: type: array maxItems: 50 items: type: integer queryText: type: string queryTextName: type: string queryTextCompany: type: string queryTextDomain: type: string queryTextTitle: type: string queryTextLocation: type: string industryFilters: type: array items: type: string companyFilters: type: array items: type: string seniorities: type: array items: type: string departments: type: array items: type: string prospectStatuses: type: array items: type: string engagementStatuses: type: array items: type: string employeeSizeFilters: type: array items: type: string revenueFilters: type: array items: type: string campaignIds: type: array items: type: integer technologies: type: array items: type: string responses: '200': description: Bulk send queued content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: jobId: type: integer nullable: true description: >- Bulk task ID. Null when every matched contact was skipped. matched: type: integer description: Contacts that matched `filters` before skip rules. queued: type: integer description: Contacts handed to the send queue. skipped: type: integer description: >- Matched contacts excluded for opt-out or no valid email. '400': description: >- Invalid filters, missing audience selector, unrecognized values, audience over the 500-contact ceiling, or invalid scheduleAt content: application/json: schema: type: object required: - message properties: message: description: A human readable error message type: string '401': description: Unauthorized content: application/json: schema: type: object required: - message properties: message: description: A human readable error message type: string '409': description: A send with this idempotency key is already in progress content: application/json: schema: type: object required: - message properties: message: description: A human readable error message type: string '422': description: Idempotency key reused with a different request content: application/json: schema: type: object required: - message properties: message: description: A human readable error message type: string security: - OAuth2: [] - ApiKeyAuth: [] components: securitySchemes: OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://login.seamless.ai/oauth/authorize tokenUrl: https://api.seamless.ai/api/client/v2/oauth/accessToken scopes: {} ApiKeyAuth: type: apiKey name: Token in: header description: API key passed via the Token header. ````