{ "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "useSend API" }, "servers": [ { "url": "https://app.usesend.com/api" } ], "components": { "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer" } }, "schemas": {}, "parameters": {} }, "paths": { "/v1/domains": { "get": { "responses": { "200": { "description": "Retrieve the user", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "The ID of the domain", "example": 1 }, "name": { "type": "string", "description": "The name of the domain", "example": "example.com" }, "teamId": { "type": "number", "description": "The ID of the team", "example": 1 }, "status": { "type": "string", "enum": [ "NOT_STARTED", "PENDING", "SUCCESS", "FAILED", "TEMPORARY_FAILURE" ] }, "region": { "type": "string", "default": "us-east-1" }, "clickTracking": { "type": "boolean", "default": false }, "openTracking": { "type": "boolean", "default": false }, "publicKey": { "type": "string" }, "dkimStatus": { "type": "string", "nullable": true }, "spfDetails": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "dmarcAdded": { "type": "boolean", "default": false }, "isVerifying": { "type": "boolean", "default": false }, "errorMessage": { "type": "string", "nullable": true }, "subdomain": { "type": "string", "nullable": true } }, "required": [ "id", "name", "teamId", "status", "publicKey", "createdAt", "updatedAt" ] } } } } } } }, "post": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "region": { "type": "string" } }, "required": [ "name", "region" ] } } } }, "responses": { "200": { "description": "Create a new domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "The ID of the domain", "example": 1 }, "name": { "type": "string", "description": "The name of the domain", "example": "example.com" }, "teamId": { "type": "number", "description": "The ID of the team", "example": 1 }, "status": { "type": "string", "enum": [ "NOT_STARTED", "PENDING", "SUCCESS", "FAILED", "TEMPORARY_FAILURE" ] }, "region": { "type": "string", "default": "us-east-1" }, "clickTracking": { "type": "boolean", "default": false }, "openTracking": { "type": "boolean", "default": false }, "publicKey": { "type": "string" }, "dkimStatus": { "type": "string", "nullable": true }, "spfDetails": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "dmarcAdded": { "type": "boolean", "default": false }, "isVerifying": { "type": "boolean", "default": false }, "errorMessage": { "type": "string", "nullable": true }, "subdomain": { "type": "string", "nullable": true } }, "required": [ "id", "name", "teamId", "status", "publicKey", "createdAt", "updatedAt" ] } } } } } } }, "/v1/domains/{id}/verify": { "put": { "parameters": [ { "schema": { "type": "number", "nullable": true, "example": 1 }, "required": false, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Create a new domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/v1/emails/{emailId}": { "get": { "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "cuiwqdj74rygf74" }, "required": true, "name": "emailId", "in": "path" } ], "responses": { "200": { "description": "Retrieve the email", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "number" }, "to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "replyTo": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "cc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "bcc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "from": { "type": "string" }, "subject": { "type": "string" }, "html": { "type": "string", "nullable": true }, "text": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "emailEvents": { "type": "array", "items": { "type": "object", "properties": { "emailId": { "type": "string" }, "status": { "type": "string", "enum": [ "SCHEDULED", "QUEUED", "SENT", "DELIVERY_DELAYED", "BOUNCED", "REJECTED", "RENDERING_FAILURE", "DELIVERED", "OPENED", "CLICKED", "COMPLAINED", "FAILED", "CANCELLED" ] }, "createdAt": { "type": "string" }, "data": { "nullable": true } }, "required": [ "emailId", "status", "createdAt" ] } } }, "required": [ "id", "teamId", "to", "from", "subject", "html", "text", "createdAt", "updatedAt", "emailEvents" ] } } } } } }, "patch": { "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "cuiwqdj74rygf74" }, "required": true, "name": "emailId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduledAt": { "type": "string", "format": "date-time" } }, "required": [ "scheduledAt" ] } } } }, "responses": { "200": { "description": "Retrieve the user", "content": { "application/json": { "schema": { "type": "object", "properties": { "emailId": { "type": "string" } } } } } } } } }, "/v1/emails": { "get": { "parameters": [ { "schema": { "type": "string", "default": "1", "example": "1" }, "required": false, "name": "page", "in": "query" }, { "schema": { "type": "string", "default": "50", "example": "50" }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "required": false, "name": "startDate", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "example": "2024-01-31T23:59:59Z" }, "required": false, "name": "endDate", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "123" }, "required": false, "name": "domainId", "in": "query" } ], "responses": { "200": { "description": "Retrieve a list of emails", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "replyTo": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "nullable": true } ] }, "cc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "nullable": true } ] }, "bcc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "nullable": true } ] }, "from": { "type": "string" }, "subject": { "type": "string" }, "html": { "type": "string", "nullable": true }, "text": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "latestStatus": { "type": "string", "nullable": true, "enum": [ "SCHEDULED", "QUEUED", "SENT", "DELIVERY_DELAYED", "BOUNCED", "REJECTED", "RENDERING_FAILURE", "DELIVERED", "OPENED", "CLICKED", "COMPLAINED", "FAILED", "CANCELLED" ] }, "scheduledAt": { "type": "string", "nullable": true, "format": "date-time" }, "domainId": { "type": "number", "nullable": true } }, "required": [ "id", "to", "from", "subject", "html", "text", "createdAt", "updatedAt", "latestStatus", "scheduledAt", "domainId" ] } }, "count": { "type": "number" } }, "required": [ "data", "count" ] } } } } } }, "post": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "from": { "type": "string" }, "subject": { "type": "string", "minLength": 1, "description": "Optional when templateId is provided" }, "templateId": { "type": "string", "description": "ID of a template from the dashboard" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "replyTo": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" } } ] }, "cc": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" } } ] }, "bcc": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" } } ] }, "text": { "type": "string", "nullable": true, "minLength": 1 }, "html": { "type": "string", "nullable": true, "minLength": 1 }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 } }, "required": [ "filename", "content" ] }, "maxItems": 10 }, "scheduledAt": { "type": "string", "format": "date-time" }, "inReplyToId": { "type": "string", "nullable": true } }, "required": [ "to", "from" ] } } } }, "responses": { "200": { "description": "Retrieve the user", "content": { "application/json": { "schema": { "type": "object", "properties": { "emailId": { "type": "string" } } } } } } } } }, "/v1/emails/batch": { "post": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "from": { "type": "string" }, "subject": { "type": "string", "minLength": 1, "description": "Optional when templateId is provided" }, "templateId": { "type": "string", "description": "ID of a template from the dashboard" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "replyTo": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" } } ] }, "cc": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" } } ] }, "bcc": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" } } ] }, "text": { "type": "string", "nullable": true, "minLength": 1 }, "html": { "type": "string", "nullable": true, "minLength": 1 }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 } }, "required": [ "filename", "content" ] }, "maxItems": 10 }, "scheduledAt": { "type": "string", "format": "date-time" }, "inReplyToId": { "type": "string", "nullable": true } }, "required": [ "to", "from" ] }, "maxItems": 100 } } } }, "responses": { "200": { "description": "List of successfully created email IDs", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "emailId": { "type": "string" } }, "required": [ "emailId" ] } } }, "required": [ "data" ] } } } } } } }, "/v1/emails/{emailId}/cancel": { "post": { "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "cuiwqdj74rygf74" }, "required": true, "name": "emailId", "in": "path" } ], "responses": { "200": { "description": "Retrieve the user", "content": { "application/json": { "schema": { "type": "object", "properties": { "emailId": { "type": "string" } } } } } } } } }, "/v1/contactBooks/{contactBookId}/contacts": { "post": { "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactBookId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "properties": { "type": "object", "additionalProperties": { "type": "string" } }, "subscribed": { "type": "boolean" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Retrieve the user", "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" } } } } } } } }, "get": { "parameters": [ { "schema": { "type": "string", "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactBookId", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "emails", "in": "query" }, { "schema": { "type": "number" }, "required": false, "name": "page", "in": "query" }, { "schema": { "type": "number" }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "ids", "in": "query" } ], "responses": { "200": { "description": "Retrieve multiple contacts", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "email": { "type": "string" }, "subscribed": { "type": "boolean", "default": true }, "properties": { "type": "object", "additionalProperties": { "type": "string" } }, "contactBookId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "email", "properties", "contactBookId", "createdAt", "updatedAt" ] } } } } } } } }, "/v1/contactBooks/{contactBookId}/contacts/{contactId}": { "patch": { "parameters": [ { "schema": { "type": "string", "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactBookId", "in": "path" }, { "schema": { "type": "string", "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "properties": { "type": "object", "additionalProperties": { "type": "string" } }, "subscribed": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Retrieve the user", "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" } } } } } } } }, "get": { "parameters": [ { "schema": { "type": "string", "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactBookId", "in": "path" }, { "schema": { "type": "string", "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactId", "in": "path" } ], "responses": { "200": { "description": "Retrieve the contact", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "email": { "type": "string" }, "subscribed": { "type": "boolean", "default": true }, "properties": { "type": "object", "additionalProperties": { "type": "string" } }, "contactBookId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "email", "properties", "contactBookId", "createdAt", "updatedAt" ] } } } } } }, "put": { "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactBookId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "properties": { "type": "object", "additionalProperties": { "type": "string" } }, "subscribed": { "type": "boolean" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Contact upserted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" } }, "required": [ "contactId" ] } } } } } }, "delete": { "parameters": [ { "schema": { "type": "string", "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactBookId", "in": "path" }, { "schema": { "type": "string", "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactId", "in": "path" } ], "responses": { "200": { "description": "Contact deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } } } } } } }