{"openapi":"3.1.0","info":{"title":"Mailtruss API","version":"1.0.0","description":"Send transactional and marketing email. Authenticate with `Authorization: Bearer <API key>`. Errors use one shape: `{ statusCode, name, message }`. Send an `Idempotency-Key` header with POST /emails to make retries safe."},"servers":[{"url":"https://mailtruss.com/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An API key such as ms_live_…"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","required":["statusCode","name","message"],"properties":{"statusCode":{"type":"integer"},"name":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/emails":{"post":{"tags":["Emails"],"summary":"Send an email","operationId":"post_emails","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":"array","items":{"type":"string","enum":["string","string"]}},"subject":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"cc":{"type":"array","items":{"type":"string","enum":["string","string"]}},"bcc":{"type":"array","items":{"type":"string","enum":["string","string"]}},"reply_to":{"type":"array","items":{"type":"string","enum":["string","string"]}},"headers":{"type":"object"},"attachments":{"type":"array","items":{"type":"object"}},"tags":{"type":"array","items":{"type":"object"}},"scheduled_at":{"type":"string","format":"date-time"},"template":{"type":"object"}}}}}},"description":"Works with both full-access and sending-access API keys.","responses":{"201":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"get":{"tags":["Emails"],"summary":"List emails","operationId":"get_emails","parameters":[{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"after","in":"query","schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/emails/batch":{"post":{"tags":["Emails"],"summary":"Send up to 100 emails in one request","operationId":"post_emails_batch","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","maxItems":100,"items":{"type":"object"}}}}},"description":"Works with both full-access and sending-access API keys.","responses":{"201":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/emails/{id}":{"get":{"tags":["Emails"],"summary":"Retrieve an email","operationId":"get_emails_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["Emails"],"summary":"Reschedule a scheduled email","operationId":"patch_emails_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["scheduled_at"],"properties":{"scheduled_at":{"type":"string","format":"date-time"}}}}}},"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/emails/{id}/cancel":{"post":{"tags":["Emails"],"summary":"Cancel a scheduled email","operationId":"post_emails_id_cancel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/domains":{"get":{"tags":["Domains"],"summary":"List domains","operationId":"get_domains","description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Domains"],"summary":"Add a domain","operationId":"post_domains","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"region":{"type":"string"},"mail_from_subdomain":{"type":"string"}}}}}},"description":"Requires a full-access API key.","responses":{"201":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/domains/{id}":{"get":{"tags":["Domains"],"summary":"Retrieve a domain and its DNS records","operationId":"get_domains_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["Domains"],"summary":"Turn click and open tracking on or off (both off by default)","operationId":"patch_domains_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"click_tracking":{"type":"boolean"},"open_tracking":{"type":"boolean"}}}}}},"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Domains"],"summary":"Delete a domain","operationId":"delete_domains_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/domains/{id}/verify":{"post":{"tags":["Domains"],"summary":"Check the domain's DNS now","operationId":"post_domains_id_verify","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/api-keys":{"get":{"tags":["API keys"],"summary":"List API keys","operationId":"get_api_keys","description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["API keys"],"summary":"Create an API key (the token is shown once)","operationId":"post_api_keys","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"permission":{"type":"string","enum":["full_access","sending_access"]},"domain_id":{"type":"string","format":"uuid"}}}}}},"description":"Requires a full-access API key.","responses":{"201":{"description":"Success. The secret in the response is shown only once."},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/api-keys/{id}":{"delete":{"tags":["API keys"],"summary":"Revoke an API key","operationId":"delete_api_keys_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/contacts":{"get":{"tags":["Contacts"],"summary":"List contacts","operationId":"get_contacts","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Contacts"],"summary":"Create or update a contact by email","operationId":"post_contacts","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"properties":{"type":"object"}}}}}},"description":"Requires a full-access API key.","responses":{"201":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/contacts/{id}":{"get":{"tags":["Contacts"],"summary":"Retrieve a contact by id or email","operationId":"get_contacts_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["Contacts"],"summary":"Update a contact","operationId":"patch_contacts_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}}}}},"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Contacts"],"summary":"Delete a contact","operationId":"delete_contacts_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/segments":{"get":{"tags":["Segments"],"summary":"List segments","operationId":"get_segments","description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Segments"],"summary":"Create a segment","operationId":"post_segments","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","rules"],"properties":{"name":{"type":"string"},"rules":{"type":"object"}}}}}},"description":"Requires a full-access API key.","responses":{"201":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/segments/{id}":{"get":{"tags":["Segments"],"summary":"Retrieve a segment","operationId":"get_segments_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Segments"],"summary":"Delete a segment","operationId":"delete_segments_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/topics":{"get":{"tags":["Topics"],"summary":"List topics","operationId":"get_topics","description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Topics"],"summary":"Create a topic","operationId":"post_topics","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"default_subscribed":{"type":"boolean"}}}}}},"description":"Requires a full-access API key.","responses":{"201":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/templates":{"get":{"tags":["Templates"],"summary":"List templates","operationId":"get_templates","description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Templates"],"summary":"Create a template","operationId":"post_templates","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","subject","html"],"properties":{"name":{"type":"string"},"subject":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"alias":{"type":"string"},"publish":{"type":"boolean"}}}}}},"description":"Requires a full-access API key.","responses":{"201":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/templates/{id}":{"get":{"tags":["Templates"],"summary":"Retrieve a template","operationId":"get_templates_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["Templates"],"summary":"Save a new (unpublished) version","operationId":"patch_templates_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"name":{"type":"string"},"alias":{"type":"string"},"subject":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"}}}}}},"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Templates"],"summary":"Delete a template","operationId":"delete_templates_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/templates/{id}/publish":{"post":{"tags":["Templates"],"summary":"Publish a version","operationId":"post_templates_id_publish","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"version":{"type":"integer"}}}}}},"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/broadcasts":{"get":{"tags":["Broadcasts"],"summary":"List broadcasts","operationId":"get_broadcasts","description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Broadcasts"],"summary":"Create a draft broadcast","operationId":"post_broadcasts","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","from","subject","html"],"properties":{"name":{"type":"string"},"from":{"type":"string"},"subject":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"reply_to":{"type":"string"},"segment_id":{"type":"string","format":"uuid"},"topic_id":{"type":"string","format":"uuid"}}}}}},"description":"Requires a full-access API key.","responses":{"201":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/broadcasts/{id}":{"get":{"tags":["Broadcasts"],"summary":"Retrieve a broadcast with delivery stats","operationId":"get_broadcasts_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Broadcasts"],"summary":"Delete a draft broadcast","operationId":"delete_broadcasts_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/broadcasts/{id}/send":{"post":{"tags":["Broadcasts"],"summary":"Send now or schedule","operationId":"post_broadcasts_id_send","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"scheduled_at":{"type":"string","format":"date-time"}}}}}},"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/broadcasts/{id}/cancel":{"post":{"tags":["Broadcasts"],"summary":"Cancel a scheduled or sending broadcast","operationId":"post_broadcasts_id_cancel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/suppressions":{"get":{"tags":["Suppressions"],"summary":"List suppressed addresses","operationId":"get_suppressions","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"reason","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Suppressions"],"summary":"Suppress an address","operationId":"post_suppressions","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"}}}}}},"description":"Requires a full-access API key.","responses":{"201":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/suppressions/{id}":{"delete":{"tags":["Suppressions"],"summary":"Remove a bounce or manual entry (complaints and unsubscribes are permanent)","operationId":"delete_suppressions_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhook endpoints","operationId":"get_webhooks","description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Webhooks"],"summary":"Create an endpoint (the signing secret is shown once)","operationId":"post_webhooks","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}}}}}}},"description":"Requires a full-access API key.","responses":{"201":{"description":"Success. The secret in the response is shown only once."},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/webhooks/{id}":{"get":{"tags":["Webhooks"],"summary":"Retrieve an endpoint","operationId":"get_webhooks_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["Webhooks"],"summary":"Update an endpoint","operationId":"patch_webhooks_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"}}}}}},"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Webhooks"],"summary":"Delete an endpoint","operationId":"delete_webhooks_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/webhooks/{id}/rotate-secret":{"post":{"tags":["Webhooks"],"summary":"Rotate the signing secret (the old one works for 24 hours)","operationId":"post_webhooks_id_rotate_secret","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success. The secret in the response is shown only once."},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/logs":{"get":{"tags":["Logs"],"summary":"List API request logs","operationId":"get_logs","parameters":[{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"after","in":"query","schema":{"type":"string"}}],"description":"Requires a full-access API key.","responses":{"200":{"description":"Success"},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}}}}