> ## Documentation Index
> Fetch the complete documentation index at: https://bavlio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a sending domain

> Adds a domain the workspace controls to the connected Bavimail account and returns the DNS records to publish at its DNS host. Inboxes on it can send once its state is ready.

## OpenAPI

```json
{
  "openapi": "3.2.0",
  "info": {
    "title": "Bavlio API",
    "version": "1.0.0"
  },
  "paths": {
    "/mail/domains": {
      "post": {
        "tags": [
          "Email"
        ],
        "operationId": "mail.addMailDomain",
        "parameters": [],
        "security": [
          {
            "bearer": []
          }
        ],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string",
                      "description": "The domain name, like example.com."
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "provisioning",
                        "awaiting_dns",
                        "ready",
                        "failed"
                      ],
                      "description": "provisioning while Bavimail sets the domain up, awaiting_dns until every check passes, ready once inboxes on it can send, or failed (see problem)."
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": [
                              "TXT",
                              "CNAME",
                              "MX"
                            ]
                          },
                          "name": {
                            "type": "string",
                            "description": "Host name the record is published on."
                          },
                          "value": {
                            "type": "string",
                            "description": "Value the record must hold."
                          },
                          "priority": {
                            "anyOf": [
                              {
                                "type": "integer",
                                "minimum": -9007199254740991,
                                "maximum": 9007199254740991
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Priority of an MX record; null when the record has none."
                          },
                          "ttl": {
                            "type": "integer",
                            "minimum": -9007199254740991,
                            "maximum": 9007199254740991,
                            "description": "Time to live, in seconds."
                          }
                        },
                        "required": [
                          "type",
                          "name",
                          "value",
                          "priority",
                          "ttl"
                        ],
                        "additionalProperties": false
                      },
                      "description": "DNS records to publish at the domain's DNS host."
                    },
                    "checks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "check": {
                            "type": "string",
                            "enum": [
                              "ownership",
                              "sending",
                              "dkim",
                              "return_path"
                            ],
                            "description": "What is checked: ownership of the domain, sending (the domain is verified to send), dkim (the DKIM signing keys) or return_path (the custom domain bounces return to)."
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "verified",
                              "failed"
                            ]
                          },
                          "detail": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Bavimail's explanation of the check's state; null when it gives none."
                          }
                        },
                        "required": [
                          "check",
                          "state",
                          "detail"
                        ],
                        "additionalProperties": false
                      },
                      "description": "State of each DNS check Bavimail runs on the domain."
                    },
                    "problem": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "What went wrong in the domain's setup, from Bavimail; null when nothing did."
                    },
                    "automatic_setup_url": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Link that publishes the records at the domain's DNS host in one step; null when the DNS host does not support it."
                    },
                    "tracking": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "hostname": {
                              "type": "string",
                              "description": "Subdomain used for open and click tracking, like track.example.com."
                            },
                            "state": {
                              "type": "string",
                              "enum": [
                                "awaiting_dns",
                                "issuing",
                                "active",
                                "failed"
                              ],
                              "description": "awaiting_dns until the records are found, issuing while the hostname is being set up, active once opens and clicks are tracked, or failed (see problem)."
                            },
                            "records": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "type": {
                                    "type": "string",
                                    "enum": [
                                      "TXT",
                                      "CNAME",
                                      "MX"
                                    ]
                                  },
                                  "name": {
                                    "type": "string",
                                    "description": "Host name the record is published on."
                                  },
                                  "value": {
                                    "type": "string",
                                    "description": "Value the record must hold."
                                  },
                                  "priority": {
                                    "anyOf": [
                                      {
                                        "type": "integer",
                                        "minimum": -9007199254740991,
                                        "maximum": 9007199254740991
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ],
                                    "description": "Priority of an MX record; null when the record has none."
                                  },
                                  "ttl": {
                                    "type": "integer",
                                    "minimum": -9007199254740991,
                                    "maximum": 9007199254740991,
                                    "description": "Time to live, in seconds."
                                  }
                                },
                                "required": [
                                  "type",
                                  "name",
                                  "value",
                                  "priority",
                                  "ttl"
                                ],
                                "additionalProperties": false
                              },
                              "description": "DNS records to publish for the tracking hostname."
                            },
                            "problem": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ],
                              "description": "Why the tracking domain failed; null when nothing failed."
                            }
                          },
                          "required": [
                            "id",
                            "hostname",
                            "state",
                            "records",
                            "problem"
                          ],
                          "additionalProperties": false
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "The tracking domain used for open and click tracking; null when none is added."
                    },
                    "created_at": {
                      "type": "string",
                      "description": "When the domain was added, as an ISO 8601 timestamp."
                    }
                  },
                  "required": [
                    "id",
                    "name",
                    "state",
                    "records",
                    "checks",
                    "problem",
                    "automatic_setup_url",
                    "tracking",
                    "created_at"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "MailRequestRejected | RequestInvalidBody",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/MailRequestRejectedEncoded"
                    },
                    {
                      "$ref": "#/components/schemas/RequestInvalidBodyEncoded"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "AuthMissing | AuthInvalid",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthMissingEncoded"
                    },
                    {
                      "$ref": "#/components/schemas/AuthInvalidEncoded"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "WorkspaceNotFound",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceNotFoundEncoded"
                }
              }
            }
          },
          "409": {
            "description": "MailNotConnected | MailAccountRestricted",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/MailNotConnectedEncoded"
                    },
                    {
                      "$ref": "#/components/schemas/MailAccountRestrictedEncoded"
                    }
                  ]
                }
              }
            }
          },
          "502": {
            "description": "MailFailed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailFailedEncoded"
                }
              }
            }
          },
          "503": {
            "description": "MailUnavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailUnavailableEncoded"
                }
              }
            }
          }
        },
        "description": "Adds a domain the workspace controls to the connected Bavimail account and returns the DNS records to publish at its DNS host. Inboxes on it can send once its state is ready.",
        "summary": "Add a sending domain",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Domain name to send from, like example.com: up to 253 characters, lowercased."
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": true
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AuthInvalidEncoded": {
        "type": "object",
        "properties": {
          "_tag": {
            "type": "string",
            "enum": [
              "AuthInvalid"
            ]
          },
          "statusCode": {
            "type": "number",
            "enum": [
              401
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "auth_invalid"
            ]
          },
          "message": {
            "type": "string",
            "enum": [
              "Bearer credential rejected"
            ]
          }
        },
        "required": [
          "_tag",
          "statusCode",
          "code",
          "message"
        ],
        "additionalProperties": false
      },
      "AuthMissingEncoded": {
        "type": "object",
        "properties": {
          "_tag": {
            "type": "string",
            "enum": [
              "AuthMissing"
            ]
          },
          "statusCode": {
            "type": "number",
            "enum": [
              401
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "auth_missing"
            ]
          },
          "message": {
            "type": "string",
            "enum": [
              "Bearer credential required"
            ]
          }
        },
        "required": [
          "_tag",
          "statusCode",
          "code",
          "message"
        ],
        "additionalProperties": false
      },
      "MailFailedEncoded": {
        "type": "object",
        "properties": {
          "_tag": {
            "type": "string",
            "enum": [
              "MailFailed"
            ]
          },
          "statusCode": {
            "type": "number",
            "enum": [
              502
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "mail_failed"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "_tag",
          "statusCode",
          "code",
          "message"
        ],
        "additionalProperties": false
      },
      "MailUnavailableEncoded": {
        "type": "object",
        "properties": {
          "_tag": {
            "type": "string",
            "enum": [
              "MailUnavailable"
            ]
          },
          "statusCode": {
            "type": "number",
            "enum": [
              503
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "mail_unavailable"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "_tag",
          "statusCode",
          "code",
          "message"
        ],
        "additionalProperties": false
      },
      "RequestInvalidBodyEncoded": {
        "type": "object",
        "properties": {
          "_tag": {
            "type": "string",
            "enum": [
              "RequestInvalidBody"
            ]
          },
          "statusCode": {
            "type": "number",
            "enum": [
              400
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "invalid_body"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "_tag",
          "statusCode",
          "code",
          "message"
        ],
        "additionalProperties": false
      },
      "MailRequestRejectedEncoded": {
        "type": "object",
        "properties": {
          "_tag": {
            "type": "string",
            "enum": [
              "MailRequestRejected"
            ]
          },
          "statusCode": {
            "type": "number",
            "enum": [
              400
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "mail_request_rejected"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "_tag",
          "statusCode",
          "code",
          "message"
        ],
        "additionalProperties": false
      },
      "MailAccountRestrictedEncoded": {
        "type": "object",
        "properties": {
          "_tag": {
            "type": "string",
            "enum": [
              "MailAccountRestricted"
            ]
          },
          "statusCode": {
            "type": "number",
            "enum": [
              409
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "mail_account_restricted"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "_tag",
          "statusCode",
          "code",
          "message"
        ],
        "additionalProperties": false
      },
      "MailNotConnectedEncoded": {
        "type": "object",
        "properties": {
          "_tag": {
            "type": "string",
            "enum": [
              "MailNotConnected"
            ]
          },
          "statusCode": {
            "type": "number",
            "enum": [
              409
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "mail_not_connected"
            ]
          },
          "message": {
            "type": "string",
            "enum": [
              "Email is not set up: connect Bavimail in Settings first"
            ]
          }
        },
        "required": [
          "_tag",
          "statusCode",
          "code",
          "message"
        ],
        "additionalProperties": false
      },
      "WorkspaceNotFoundEncoded": {
        "type": "object",
        "properties": {
          "_tag": {
            "type": "string",
            "enum": [
              "WorkspaceNotFound"
            ]
          },
          "statusCode": {
            "type": "number",
            "enum": [
              404
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "workspace_not_found"
            ]
          },
          "message": {
            "type": "string",
            "enum": [
              "No such workspace for this account: save a company profile or pick a workspace you belong to"
            ]
          }
        },
        "required": [
          "_tag",
          "statusCode",
          "code",
          "message"
        ],
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "bearer": {
        "description": "Send `Authorization: Bearer <token>`. The token is an API key, which starts with `bav_` and comes from creating an API key or starting a registration, or the access token of a Bavlio sign-in.",
        "type": "http",
        "scheme": "Bearer"
      }
    }
  },
  "security": [],
  "tags": [
    {
      "name": "Registration",
      "description": "Open a Bavlio account without signing in. Starting a registration returns an API key for a new ephemeral account, which becomes permanent once its email address is verified."
    },
    {
      "name": "Authentication",
      "description": "Identify the calling account, finish a registration and manage the account's API keys."
    },
    {
      "name": "Account",
      "description": "The account behind your sign-in, and deleting it."
    },
    {
      "name": "Workspaces",
      "description": "A workspace holds the company profile, outreach schedule, team, campaigns and billing Bavlio works with. Calls that act in a workspace use the one whose id is in the bavlio-workspace header, or the account's default workspace when the header is absent."
    },
    {
      "name": "Teams",
      "description": "Manage who belongs to a workspace: its members, their roles and the invitations to join it. Each workspace's plan sets how many team seats it has."
    },
    {
      "name": "Campaigns",
      "description": "A campaign finds leads that match an ideal customer profile (ICP) and buying signals, and reaches out to them through its sequence of LinkedIn and email steps."
    },
    {
      "name": "Lead imports",
      "description": "Bring your own leads: preview a CSV, confirm which column holds what, then import it into a campaign, where the leads go through the same sequence as the ones Bavlio finds."
    },
    {
      "name": "Sequences",
      "description": "A campaign's sequence is the steps Bavlio runs for each lead: profile visits, likes, invites, LinkedIn messages, emails, waits and conditions. Every message and email waits in the review queue for approval before it is sent."
    },
    {
      "name": "Inbox",
      "description": "Conversations with the people your campaigns reached and, for accounts that opt in, your other LinkedIn and email conversations: read them, reply to them and follow changes live."
    },
    {
      "name": "Reviews",
      "description": "Messages and emails go to a lead only after someone approves them. The review queue holds the replies Bavlio drafted for people who answered and the messages and emails it drafted for campaign sequences."
    },
    {
      "name": "Billing",
      "description": "The plans on offer and the workspace's subscription and usage. Plan changes, cancellation and the billing portal need the workspace owner or an admin."
    },
    {
      "name": "LinkedIn",
      "description": "Connect the LinkedIn accounts your campaigns send from, confirm their sign-ins, choose the country LinkedIn sees them from, and disconnect them."
    },
    {
      "name": "Meetings",
      "description": "Meetings booked through the workspace's calendar tool (Google Calendar, Calendly or Cal.com), and the calendar connection that imports them."
    },
    {
      "name": "Email",
      "description": "Connect a Bavimail account, add sending domains and tracking domains, and create the inboxes campaigns send email from."
    }
  ],
  "servers": [
    {
      "url": "https://api.bavlio.com"
    }
  ]
}
```